Termgram

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:

# ~/.config/termgram/config.toml
api_id = 123456
api_hash = "0123456789abcdef0123456789abcdef"

3. Login

termgram login            # enter your phone number, receive a code
termgram login 12345      # verify the code

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:

cargo build --release
cp target/release/termgram ~/.local/bin/
cp target/release/termgram-mcp ~/.local/bin/
cp target/release/termgram-notify ~/.local/bin/

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

termgram send saved 'hello'                      # plain text
termgram send saved '**bold** text' --format md  # rich text
termgram send saved 'see you' --date '14/09 17:00' --date '15/09 09:00'
termgram send saved 'photo' --file shot.png      # photo / document / voice
termgram send saved --file a.png --file b.png    # album
termgram send someone --at '16:00'                 # scheduled
termgram send saved 'into a topic' --topic 42    # forum topic
termgram send saved 'reply me' --reply 1108131   # reply

--date repeats to add more tappable date chips. Formats are plain, md, and html.

Everyday commands

termgram dialogs                 # all chats, unread counts, last message
termgram messages saved          # recent messages, newest last
termgram watch saved             # tail a chat live
termgram watch --unread          # survey chats with unread messages
termgram read saved              # mark as read
termgram sync                    # index everything locally
termgram search 'query'          # search the local mirror
termgram search --chat someone 'query'
termgram poll saved 'which one' red green blue --multi --anon
termgram react saved 1108131 🎉  # Premium required to send
termgram profile someone          # full profile
termgram status someone           # online status
termgram kick group user          # and: ban, unban, promote, members, pinned
termgram export ~/termgram-backup

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

termgram sync              # index dialogs + recent messages
termgram search 'query'    # offline search across all chats
termgram cached someone 50  # last 50 cached messages
termgram searchall 'x'     # global Telegram search (API)
termgram searchin someone 'x' # search inside one chat (API)

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:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "termgram": {
      "type": "local",
      "command": ["/home/you/.local/bin/termgram-mcp"],
      "enabled": true
    }
  }
}

Or in any standard MCP client:

{
  "mcpServers": {
    "termgram": {
      "command": "/home/you/.local/bin/termgram-mcp",
      "args": []
    }
  }
}

termgram-mcp --catalog starts a session-less mode that answers only MCP discovery calls (no Telegram connection). It exists so directory services can introspect the server without credentials.

Tools

Every CLI command is exposed as a tool. send accepts the same unified model (text, files, format, dates, reply, topic, at), plus poll, topics, watch, upload, album, voice, schedule, scheduled, cancel, edit, draft, drafts, react, reactions, search / searchin / searchall, sync, mirror access, admin tools, and export / import / wipe.

Push notifications

The MCP server pushes every new incoming message to the client as a server→client custom notification:

method: notifications/termgram/message
params: {
  "chat":  "-1001234567890",   // dialog id (negative = group/channel)
  "id":    423,
  "at":    1770000000,         // unix timestamp
  "out":   false,              // true when the message is your own
  "from":  "Alice",            // sender display name
  "text":  "hey, check this",
  "media": "photo"             // photo|document|sticker|contact|poll|…, null if none
}

Pushes are off by default. Control them with the notify tool:

SSE stream

termgram-notify is a tiny standalone HTTP server (no extra deps, one process). It streams the same new-message events as text/event-stream:

termgram-notify &          # binds 127.0.0.1:6837
curl -N http://127.0.0.1:6837/events                 # all chats
curl -N 'http://127.0.0.1:6837/events?chat=178220800' # one chat

Each event is a single data: line with the same JSON shape as the MCP notification, followed by a blank line. A : ping comment heartbeat arrives every 15 seconds to keep the connection alive. Override the port with TERMGRAM_NOTIFY_PORT, filter with the query string, and connect from a browser, curl, or any SSE client.

A note on streams

An MCP or SSE connection streams the account's incoming events. Messages tied to an exchange that happens on a different live session (for example, another terminal's running termgram process replying to a bot) can stay on that session's feed instead of reaching your stream. In the common case the same process that sends also pushes, so nothing is missed. The MTProto layer guarantees constant streaming, not per-session lockstep.

How it's built

Single Rust workspace, four crates:

All three binaries share one session and config. The core exposes a broadcast Update stream so the CLI, MCP server and notifier all wake instantly on new messages.

Security

• Credentials (api_id, api_hash) and your session live only in ~/.config/termgram/, never in this repository.
• The notifier binds to 127.0.0.1 only.
• Nothing in the push payloads stores or forwards your secrets.

Notes

• Reacting with new emoji requires Telegram Premium; reading reactions works for everyone.
• Two termgram processes on the same account share one session.db. Run long-lived watchers on their own; concurrent write commands may surface database is locked.

Contributing

This project is actively looking for maintainers. The current maintainer uses termgram daily but isn't adding features; if you want it to keep evolving, the maintainer seat can be yours. Report bugs, open issues for direction, send PRs, or volunteer to co-maintain. Start with CONTRIBUTING.md. Small PRs merge fast; big ones get discussed in an issue first.

License

MIT