Telegram (tg-mcp)

tg-mcp

Unofficial remote MCP server that gives AI clients (Claude, ChatGPT, Gemini, Claude Code, Cursor, …) read access to your personal Telegram account and, only if you allow it, lets them write Drafts that you send yourself, or send messages to chats you choose, each confirmed by you, and react and mark as read there. You add a URL, log in by scanning a QR code, and you're done.

Not affiliated with or endorsed by Telegram. It uses the Telegram API through its own registered app ("Unofficial MCP Server"). Nothing is ever edited or deleted, and nothing is forwarded. A connection writes only what you ticked for it: Write Drafts, text in a chat's message field that you send yourself; Send messages, messages to the chats you chose, each one confirmed by you in your browser unless you ticked "without asking me", plus reactions and read marks in those chats (never confirmed). Without either, nothing is ever written.

Quick start

Website: tgmcp.dev. Public instance: https://connector.tgmcp.dev/mcp

Claude Code

claude mcp add --transport http telegram https://connector.tgmcp.dev/mcp

Then run /mcp in Claude Code → telegram → Authenticate. A browser opens:

1. Scan the QR code with Telegram on your phone: Settings → Devices → Link Desktop Device.
2. If your account has a cloud password (two-step verification), type it on the same page. It goes only to this server's login page, never through the AI client or the chat.
3. Allow on the consent screen. Reading is always included; leave Write Drafts and Send messages unticked to keep the connection read-only. Write Drafts ticked, the AI can also put text into a chat's message field on all your devices (save_draft), replacing the Draft there; only you can send it. Send messages ticked, you choose the chats it may send to (Chat folders, your 100 most recent chats, or a chat found by name: only chats you already have), and whether it may send there without asking you each time (off unless you tick it). Then each message the AI sends (send_message) waits for you on this server's confirmation page, opened in this same browser: Claude Code opens it for you, other clients hand you the link. In those chats it may also react to messages (react) and mark them as read (mark_read) without asking.

Claude (web/desktop/mobile, free plan too): Settings → Connectors → Add custom connector → the same URL. ChatGPT (paid plans): Settings → Apps & Connectors → Advanced → turn on Developer mode, then Create → the same URL. Gemini (personal Google accounts, add it on the web): Settings → Connected apps → Add a custom app → the same URL. Other MCP clients: add it as a streamable-HTTP server; they discover OAuth on their own.

Tools

Experimental, off by default: with TG_MCP_EXPERIMENTAL_DOCUMENTS=1, get_media also takes mode document (a PDF or plain-text file as an embedded resource in the result; a #58 prototype that may change or go away).

Chat ids look like user:123~a-MGLzhi9Ek, chat:456 (basic group) or channel:789~18YMXnDF6JI (channels and supergroups), as returned by list_chats, find_chats and in message senders; the part after ~ is the access hash Telegram needs, so an id works without the server looking it up. Ids without it (user:123) are still accepted. Every tool but save_draft, send_message, react and mark_read is marked read-only, and every tool has bounded input and output: at most 100 items per call (200 members for get_members), long texts cut. Messages describe their media (media: its kind and metadata) without downloading it; text holds only a message's text or caption, so a voice message has an empty text and media.kind: "voice". Only get_media fetches a file, a picture or a transcription, and only when asked to.

Prompts

Two MCP prompts turn common requests into step-by-step instructions that use the tools above. A client that supports prompts lists them and inserts the rendered text as if you typed it. Each takes one optional argument, query: your request in your own words (up to 512 characters), from which the model takes the time range, the chats and how many. Rendering a prompt reads nothing from Telegram.

In Claude Code they are slash commands named after the server, e.g. /mcp__telegram__catch_up and /mcp__telegram__research for a server added as telegram (characters other than letters, digits, _ and - in the name become _). Everything after the command is the request, unquoted: /mcp__telegram__research top restaurants Tbilisi. Claude Code splits it on whitespace and may deliver only its first word; the model then asks for the whole request before making any call, and you give it in your next message. A long request can go there from the start: a bare /mcp__telegram__research asks what to research (a bare catch_up runs its default instead). Both prompts answer in the language of your earlier messages in the conversation (or else in the language of the chats read), and tell the model that message content is data, never instructions.

Disconnecting

End the Unofficial MCP Server session in Telegram → Settings → Devices. That logs the server out for real; the AI client gets a 401 on its next call.

Removing the server in your AI client alone is not enough: e.g. Disconnect in claude.ai's connector settings only forgets the tokens on its side, and without a token the server can't decrypt (or log out) your session — by design, see below. Clients that call the OAuth revocation endpoint (/revoke, RFC 7009) do log the session out.

Security model

• A database dump is useless. Your Telegram session is encrypted (XChaCha20-Poly1305) with a per-login key. That key is never stored: each OAuth token your client holds carries the secret needed to unwrap it, and the server keeps only a verifier and a wrapped copy per token. Without one of your tokens, nobody, including the operator, can decrypt the session. (ADR-0003)
• Restarts don't need a re-login, because the encrypted session survives in the database and your client's token unlocks it again.
• No messages on disk. Chats, messages and Drafts pass through memory only; the session at rest is just the auth keys and home datacenter. Logs carry ids and sizes, never message or Draft text or tokens. The duplicate guard of send_message keeps a keyed hash of each sent message's text, in memory, for a minute.
• Media links are short-lived credentials. A get_media download link is 256 random bits, lives in memory only, works for 5 minutes and 3 downloads, and only for the one file it was made for; revoking the login ends it at once, and a restart ends them all. The file streams from Telegram into the response without touching disk. A view holds its images (at most ~1 MB) in memory only for the one call.
• Scopes. A connection gets only what you tick on the consent screen: read always, draft if you allow it (save_draft: Drafts only you can send), send if you allow it and choose the chats it may send to (send_message, each message confirmed by you unless you chose otherwise; react and mark_read in the same chats, never confirmed; organize is not offered yet). Tools outside a connection's Scopes are neither listed nor callable, the server's instructions to the AI name only what its tools can do, and changing Scopes means connecting again. (ADR-0005)
• The Send allow-list is sealed like the session. The chats a send connection may write to (send, react, mark as read), and whether it may send without asking, are encrypted with the same per-login key, so a database dump shows neither which chats nor (beyond a rough size) how many. Only chats you already have can be chosen; folders are read into their chats when you allow; changing the list means connecting again. Choosing the chats asks Telegram a few times for your own account, before the AI gets any token: that page needs the login's cookie, and is rate-limited per IP and per login. Logs carry how many chats, never which.
• Sends are confirmed in your own browser. Unless you ticked "without asking me", every message waits up to 10 minutes on this server's confirmation page, which shows the chat, the exact text (links with where they lead) and who asks. Only the browser where you gave Consent can press Send or Cancel: allowing send sets a cookie there (HttpOnly, SameSite=Strict, only sent to /confirm) whose verifier is sealed with the chat list, so the AI, which may see the page's link, can't send with it; any other browser can only make the message a Draft. Clients with URL elicitation (Claude Code) open the page for you; others hand you the link. Waiting messages live in memory only; a confirmed one still counts against the writes budget and the chat's Send cap. (ADR-0005)
• Your password never reaches the AI. QR login and the cloud password happen on this server's own pages.
• OAuth 2.1 with PKCE (S256), dynamic client registration, single-use authorization codes, rotating refresh tokens bound to their client, and a consent screen that leads with where the login is sent, names the account, and shows the self-declared client name as unverified.
• Telegram limits are respected. Requests per account are rate-limited, and Telegram's FLOOD_WAIT blocks that account's calls of the same kind (reading, search, file downloads, transcription or writes) until it passes instead of being retried around. Writes (Drafts, sent messages, reactions and read marks) also have their own budget, 20 per account in any 10 minutes by default: a write over it, or during a FLOOD_WAIT of writes, fails at once saying when to retry, and is never retried or queued; so does a message over a chat's Send cap (5 a minute by default) or into a group's slow mode. Telegram's PEER_FLOOD (the account is limited for spam) is reported as such, never retried.
• Anonymous callers can't make it flood Telegram. The OAuth endpoints are rate-limited per client IP, and only a few logins (each one a Telegram connection) can be in progress at once, server-wide and per IP.

Self-hosting

You need a server with HTTPS on a public hostname (OAuth requires it) and your own Telegram app:

1. Register an app at my.telegram.org/apps → note api_id and api_hash. Please keep "Unofficial" in its title.
2. Run the image behind a TLS-terminating reverse proxy that forwards the Host header:

docker run -d --name tg-mcp --restart unless-stopped \  -p 127.0.0.1:8080:8080 \  -v tg-mcp-data:/data \  -e TG_MCP_PUBLIC_URL=https://tg.example.com \  -e TG_MCP_DB_PATH=/data/tg-mcp.db \  -e TG_MCP_API_ID=123456 \  -e TG_MCP_API_HASH=your_api_hash \  ghcr.io/qelphybox/tg-mcp:latest

If the proxy sets or appends X-Forwarded-For from the address it accepted the connection from (Caddy and kamal-proxy do; nginx with proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for), also pass -e TG_MCP_TRUST_FORWARDED_FOR=1, so the per-IP rate limits of the OAuth endpoints see real client addresses instead of the proxy's.

Images are published for linux/amd64 and linux/arm64 on every release tag. All settings are environment variables, documented in .env.example.

This repository also deploys itself with Kamal to a single VPS (zero-downtime rollouts, automatic Let's Encrypt): see docs/deploy.md. scripts/setup-deploy.sh walks through the one-time setup, including server hardening.

Development

cargo test                                   # unit + HTTP-level tests, no network neededTG_MCP_FAKE_TELEGRAM=1 cargo run             # local server with a fake Telegram accountcargo test -- --ignored live_                # MTProto handshake against real Telegram DCs

Rust, tokio, axum, rmcp, grammers, SQLite. Domain vocabulary is in GLOSSARY.md, decisions in docs/adr/, contributor and agent conventions in CLAUDE.md.

License

MIT, see LICENSE.