Telegram MCP server in Rust
MCP is the protocol an AI agent uses to call tools. This Rust server gives the agent exact Telegram context and managed attachments without exporting the account. In my setup the agent drafts a reply and it goes out only after my confirmation; approval mode is optional, so an installation without it sends directly with weaker guarantees. The result survives restart.
- What the agent receives
- AI selects one dialog and message, then reads a bounded window around it without exporting the account.
- What stays in the workspace
- The original file is downloaded into a content-addressed workspace. The host can create a modified sibling without overwriting the source bytes.
- What a reply requires
- In my setup, before delivery the server binds the account, recipient, reply target, text, payload hash, and expiry to one private approval card, and nothing is sent until I confirm it. The result is stored durably.
Public demo and source
v0.2.0 is the current public pre-1.0 build. The reproducible demo uses the real MCP binary without Telegram credentials or network delivery.
- 14 typed toolsEvery tool has an input schema, output schema, MCP annotations, and the same structured result envelope after argument parsing.
- Compiled server over stdioThe integration test launches the compiled server and connects an rmcp client through operating-system stdio.
- File identityThe demo finds a contract message, downloads its PDF, creates a changed sibling, replies with the bound SHA-256, and reads the result back.
- Restart statePrepared text, approval state, Telegram random_id, and the final send result remain available after restart.
The complete job
An AI agent using the server can locate a conversation, recover the exact message context, move an attachment into a controlled local workspace, and prepare a reply without receiving an unbounded account export.
The server is an interface with no agent of its own. Reasoning and file changes happen in the host; the Rust server owns exact account, chat, and message references, bounded reads, approval state, and the send result.
What the public demo actually runs
HOST AGENT
find message | read context
↓
TELEGRAM MCP (Rust over stdio)
download immutable PDF | return path + SHA-256
↓
MANAGED WORKSPACE
host creates a modified sibling
↓
PREPARED REPLY
exact target | reply ID | payload hash
↓
SEND + RESULT
durable state | Telegram message IDWhat the server exposes
- MCP tools
- 14 typed operations
- Message access
- bounded search and context
- Attachments
- immutable originals + SHA-256
- Text approval
- private Telegram button
- Send recovery
- durable SQLite ledger
- Protocol
- stable MCP 2025-11-25
Why approval is durable state
- Problem
- A process can stop after Telegram accepts a message but before the caller records the result. A copied or stale callback must not become permission to send again.
- Solution
- Persist the prepared payload, stable Telegram random_id, exact approval card, approving user ID, expiry, and Telegram result with the sent message ID. Recovery reads the same operation and does not construct a replacement send.
- Why not the other option
- After a transport failure, a direct send tool cannot tell whether the message was never sent or the response was lost. Retrying can create a duplicate.
Why chat and file references are explicit
- Round-trippable chats: Returned chat references can be used again as usernames or canonical numeric peer IDs; private peers are not guessed from interface labels.
- Managed file roots: Uploads must resolve inside the selected account's cache root, so an arbitrary host path cannot be sent through Telegram.
- Immutable originals: Downloaded source files are content-addressed. A changed file becomes a new sibling with its own hash, and the original stays untouched.
- One session owner: Only one live process can own the Telegram session and approval worker at a time.
Implementation
- Core
- Rust 2024, Tokio, clap
- MCP
- rmcp 1.7.0, stdio, serde, schemars
- Telegram
- ferogram, MTProto, Bot API approval callback
- State
- SQLite ledger, content-addressed attachment cache