liagha/termgram

Telegram in the terminal. A complete MTProto client, an MCP server, and a
push stream, in one place.
termgram talks to Telegram natively over MTProto (via the grammers stack).
No Bot API, no external services. One unified command sends text, rich media,
tappable date chips and scheduled messages. A local mirror makes search
instant. And two hooks let your own tools react the moment a message lands:
- termgram-mcp, an MCP server: every CLI command becomes a tool, and new
messages are pushed to the client as server→client notifications.
- termgram-notify, an SSE stream: a plain HTTP endpoint any script can
subscribe to.
For people who live in the terminal and want AI on top of their chats.
Highlights
- **One unified send pipeline.** Text, plain/markdown/html formatting
parsed into real Telegram entities, tappable date chips, photos, documents,
voice notes, albums, replies, scheduling, forum topics. All through one
send command.
- **Local search mirror.** sync once, then search offline-instant across
every chat. Missing chats auto-sync on demand, with a live API fallback.
- **Full chat tooling.** Polls, reactions, drafts, pins, folders, contacts,
members, kick/ban/promote, export/import/wipe.
- **Push, not polling.** New messages arrive through a broadcast signal;
wait blocks server-side on a real Telegram push and returns instantly.
- **Per-chat notification filter.** Tell the MCP server which chats to push,
or push everything.
- **One auth for everything.** A single session drives the CLI, MCP server and
notifier. Multiple accounts supported.
Getting started
1. Register an app
Telegram needs an API ID and hash per client. Create one at
my.telegram.org (any value works; it's your
own account).
2. Configure
termgram keeps everything under ~/.config/termgram/. On first run it writes
a config.toml template; fill it in:
3. Login
Your session is stored in ~/.config/termgram/session.db. One login is shared
by the CLI, the MCP server and the notifier.
4. Install the binaries
Build the workspace and copy the three binaries into your PATH:
Or install each crate from crates.io with cargo install termgram-cli termgram-mcp
termgram-notify, or from source with cargo install --path crates/cli,
cargo install --path crates/mcp, cargo install --path crates/notify.
Prebuilt binaries are attached to every GitHub
release.
CLI
Send anything, one command
--date repeats to add more tappable date chips. Formats are plain, md,
and html.
Everyday commands
Full surface: me men dialogs messages read watch send edit delete forward pin
react reactions drafts draft profile set block unblock typing status scheduled
cancel contacts folders folder-new folder-rm pinned members kick ban unban
promote grab export import wipe poll topics search searchin searchall sync
cached.
Text formats
Markdown and HTML are parsed into real Telegram entities before sending.
Dates rendered this way become tappable chips, not raw text.
Local search mirror
Chat names match case-insensitively (someone = SOMEONE). Searching a chat that
isn't mirrored auto-syncs it; if the mirror still has nothing, it falls back to
a live API search.
MCP server
termgram-mcp speaks the Model Context Protocol over stdio. Register it
with your MCP client; for opencode:
Or in any standard MCP client:
termgram-mcp --catalog starts a session-less mode that answers only MCP