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?

• Safe by default — boots in read-only mode with a small inbox/reader profile; write and quota-consuming tools are hidden from the model, not merely blocked, until you turn them on.
• Human approval that does not depend on your client — destructive tools ask a person 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.
• Real user accounts, not just bots — built on TDLib (via tdlight-java), so an agent can read and act on your actual account, not only a Bot API subset.
• Isolated multi-account — each account gets its own session, mandatory selection, and scoped API keys; reads never fan out across accounts.
• Two transports — STDIO for Claude Desktop / Cursor / VS Code / Codex, Streamable HTTP for a managed service.
• No JDK to install — runtime-inclusive release bundles for Windows, Linux x64/ARM64, and Apple-silicon macOS, with checksums, an SBOM, and signed container digests.

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.”

In this mode write and quota-consuming tools are absent from the tool list entirely, so the model has nothing destructive to call. Switch to MCP_READ_ONLY=false only after you have reviewed the surface. When you do, add MCP_DESTRUCTIVE_APPROVAL=auto so deletes, bans and leaves wait for your answer through host elicitation where available, or through the server's loopback page otherwise, rather than trusting the model's own "confirmed": true.

Connect your client

Generate the entry instead of transcribing one — it fills in the key your client actually expects and pins the version it was generated from:

telegram-mcp config --client claude

--client claude-code|cursor|vscode|codex switches target — Codex gets TOML, VS Code gets the servers key it actually reads, Claude Code gets the explicit transport type. --writes enables write tools and the approval prompt that guards the destructive ones — pair it with a write-capable --profile inbox|community-admin|all, since the default reader surface hides write tools before read-only mode is consulted. --docker default emits a container entry with a pinned image, and --http default emits the shared-daemon entry for Claude Code, Cursor, VS Code, or Codex. Claude Desktop does not read remote servers from claude_desktop_config.json; add a network-reachable remote endpoint under Settings → Connectors instead. Claude remote connectors do not accept the generator's custom API-key header, so this server must be exposed over HTTPS with MCP_AUTH_MODE=oauth. The generator therefore rejects --client claude --http.

STDIO is the low-friction path for desktop clients. The generated entry looks like:

{
  "mcpServers": {
    "telegram": {
      "command": "telegram-mcp",
      "args": ["serve", "--transport", "stdio"],
      "env": {
        "TDLIB_API_ID": "123456",
        "TDLIB_API_HASH_FILE": "/absolute/path/to/telegram-api-hash",
        "MCP_TOOL_PROFILE": "inbox",
        "MCP_READ_ONLY": "true"
      }
    }
  }
}

• Claude Desktop — add the block above to claude_desktop_config.json, then quit the app from the tray and start it again. Use Settings → Developer → Edit Config to open the file: it points at the right copy for your build. Editing %APPDATA%\Claude by hand works only for the installer build — the Microsoft Store build is packaged as MSIX and keeps its config in %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\ instead.
• Cursor — add it to ~/.cursor/mcp.json (or Settings → MCP → Add).
• VS Code — use .vscode/mcp.json; VS Code names the top-level key servers instead of mcpServers and requires an explicit "type": "stdio" or "type": "http".

For a managed HTTP deployment instead of STDIO:

docker run --rm -p 127.0.0.1:8080:8080 \
  -e TDLIB_API_ID -e TDLIB_API_HASH -e MCP_API_KEY \
  ghcr.io/tolboy/telegram-mcp-tdlib:latest

See CLI and STDIO, interactive authentication, and client compatibility for exact platform/client variants.

Recipes

Copy-paste configurations and prompts for real tasks, each with the smallest tool surface that can do the job: summarize your inbox, find a lost message, research public groups, read-only community health check, and draft replies without sending — index in docs/recipes.

How it compares

Most Telegram MCP servers wrap the Bot API or a Telethon user session and expose every capability to the model at once. This project optimizes for connecting an agent to a real account you care about, safely:

A fuller architectural comparison (TDLib vs Telethon vs Bot API, and why "hidden, not blocked" matters) is in docs/COMPARISON.md. The detailed, dated benchmark against the leading public servers — including features deliberately declined (raw MTProto escape hatch, ownership transfer, bulk contact export) — is in PUBLIC_BENCHMARK_AND_ROADMAP.md.

Tool profiles

You don't expose 110 tools on day one. MCP_TOOL_PROFILE narrows the advertised surface before a client ever sees it, without weakening account scoping, read-only mode, confirmation, audit, or anti-spam:

See TOOL_PROFILES.md for the exact intent of each surface.

Features