telegram-mcp

Let your AI agent read your Telegram.

A small server that runs in your own Cloudflare account, signs in as you (a normal Telegram login, like Telegram Desktop), and lets any MCP client (Claude Code, Claude Desktop, anything that speaks MCP) list, read and search your chats. It is read-only: nothing in it can send, edit or delete a message.

Ask your agent things like:

• "What did Dana say about the flights?"

• "Search all my chats for the invoice number."

• "Summarize what I missed in the family group today."

Status: pre-release. The plumbing is tested (see Status); the Telegram login and the read tools have not yet been run against a real account. Try it on a spare account first.

How it works

Telegram keeps your whole history on its servers, so there is nothing to sync or mirror. Every tool call is a live request to Telegram through mtcute (an MTProto client) running inside a Durable Object. The only thing stored is the Telegram login itself, in that object's SQLite. No computer of yours needs to stay on.

Related MCP server: my-tg-mcp

Set it up

You need a Cloudflare account, Node 22.18+, and the Telegram app on your phone.

1. Get Telegram API credentials. Log in at https://my.telegram.org, open API development tools and create an app. Keep the api_id and api_hash private.

2. Deploy.

git clone https://github.com/sigman78/telegram-mcp
cd telegram-mcp
npm install

# A place for the sign-in tokens. Paste the id it prints into wrangler.jsonc.
npx wrangler kv namespace create OAUTH_KV

npx wrangler secret put TG_API_ID
npx wrangler secret put TG_API_HASH
npx wrangler secret put OWNER_PASSWORD     # 12+ characters. Make it long.

npm run deploy

Wrangler prints your URL, e.g. https://telegram-mcp.your-name.workers.dev. To keep your own KV id out of git, put it in wrangler.local.jsonc (git-ignored) and deploy with npm run deploy:local. Times are shown in UTC unless you set a TIMEZONE var (an IANA zone such as Europe/Berlin) in the config.

3. Link your account. Open <your-url>/setup, enter the password, and scan the QR code in Telegram (Settings > Devices > Link Desktop Device). If the account has two-step verification, the page asks for that password too.

4. Connect your agent.

claude mcp add --transport http telegram https://your-url/mcp

Then type /mcp and sign in with the password. Other clients: point them at the same /mcp URL.

Tools

Security

Your Telegram session is a key to your whole account. Treat a deployment like a password manager.

• The session lives only in the Durable Object. No messages are stored anywhere.

• /mcp needs an OAuth token, issued only after you type the password in the browser that started the approval. The approval screen names the app and shows where it will be redirected. Client registration is open, so read it.

• Password guesses are throttled, but that slows a guesser and does not stop one. The strength of the password is the real protection.

• Browser sessions last 14 days and cannot be revoked individually; changing OWNER_PASSWORD signs everything out.

• Any approved client can call relink.

• Client registration writes to KV and needs no login, so it is capped at 10 per minute per IP (the ratelimits binding in wrangler.jsonc). The cap is approximate, so a determined flood could still use up the free KV write quota and lock you out until it resets.

• This uses Telegram's API unofficially, with your own api_id. Keep call volume modest; heavy use triggers FLOOD_WAIT.

• To end access: remove the device in Telegram (Settings > Devices), call relink, or delete the Worker.

More in SECURITY.md.

Status

Verified: typecheck and unit tests; mtcute connects to Telegram and makes calls from a deployed Durable Object; the stored login survives a client restart; OAuth registration, consent, sign-in, token exchange and MCP calls end to end; browser-bound approvals; password throttling; idle close not interrupting a long read.

Not yet verified with a real account: QR login, the 2FA step, the read tools against real chats, and that scan notices still arrive with the update stream off. If the setup page stays on the QR code for up to ~30 s after a scan and never shows "Scanned", that last point is the cause.

Related projects

Other Telegram MCP servers exist, mostly local and mostly able to send; for example chigwell/telegram-mcp and freQuensy23-coder/telegram-mcp-serverless (mtcute on Workers). This one differs in being read-only, OAuth-gated for MCP clients, and linked from a web page by QR code.

License

MIT.