Telegram MCP Server

Telegram MCP Server

Telegram MCP for real accounts — safe by default, TDLib-powered, production-ready.

A local-first Model Context Protocol server that gives an AI agent real Telegram-account access without handing it the keys to your account. It starts read-only, hides write tools until you opt in, and runs over STDIO for desktop clients or Streamable HTTP at /mcp for managed deployments.

Why this one?

write and quota-consuming tools are hidden from the model, not merely blocked, until you turn them on.

• Safe by default — boots in read-only mode with a small inbox/reader profile;

first: through the MCP host where elicitation exists, otherwise on a single-use loopback page this server hosts. Either way the question leaves and the answer returns outside the model's turn, so an injected instruction can make the model request a ban, not approve one.

• Human approval that does not depend on your client — destructive tools ask a person

can read and act on your actual account, not only a Bot API subset.

• Real user accounts, not just bots — built on TDLib (via tdlight-java), so an agent

scoped API keys; reads never fan out across accounts.

• Isolated multi-account — each account gets its own session, mandatory selection, and

for a managed service.

• Two transports — STDIO for Claude Desktop / Cursor / VS Code / Codex, Streamable HTTP

Apple-silicon macOS, with checksums, an SBOM, and signed container digests.

• No JDK to install — runtime-inclusive release bundles for Windows, Linux x64/ARM64, and

The image is an illustrative mockup; a real screencast is on the way.

Safe first run

Runtime-inclusive releases need no JDK, Gradle, Git, Python, or Node.js. Use a test account for your first run if you can.

1. Install (macOS Apple silicon / Linux with Homebrew):

brew install --formula https://github.com/tolboy/telegram-mcp-tdlib/releases/latest/download/telegram-mcp.rb

Windows with Scoop:

scoop install https://github.com/tolboy/telegram-mcp-tdlib/releases/latest/download/telegram-mcp.json

2. Log in with a QR scan — the one-time code never touches your shell history:

telegram-mcp auth --method qr

3. Check the session is ready — this reads local state and starts no server:

telegram-mcp session doctor

Do not run serve --transport stdio yourself to try it out. With STDIO your AI client starts the server and owns its lifetime; a copy you launched in a terminal holds the TDLib session, and the client's own copy then exits with code 2 because it cannot lock td.binlog. Give the command to the client instead (below) and let it do the starting.

Then try a first prompt that cannot change anything:

“Summarize my last 20 conversations. Do not send or modify anything.”

Shortened. The full README is on GitHub.