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.
• Sends an agent can retry — an idempotency_key turns a lost response into a stored receipt instead of a duplicate message; an unconfirmed send is reported as UNKNOWN, never silently resent.
• 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".

To share one local process across clients, use telegram-mcp daemon start and telegram-mcp daemon attach --client cursor (or codex, vscode, claude-code). See managed local daemon for status, stop and onboarding.

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

For reusable agent instructions, install the free Telegram Inbox Assistant skill. Requires server 1.17.2 or later. Shared-daemon users of Claude Desktop can use the optional tools bridge, included in runtime packages with its Python dependency instructions. Its setup guide includes client configuration templates and explains the separately required local server and Telegram authorization. The skill summarizes and searches in read-only mode.

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:

| Dimension | This server | Typical Telethon / Bot-API MCP servers | |---|---|---| | Account access | Real user account via TDLib (tdlight-java) | Often bot-only, or a single Telethon user session | | Default posture | Read-only; write/quota tools hidden until enabled | Usually all tools exposed from the start | | Multi-account | Isolated sessions, mandatory selection, scoped keys, no cross-account read fan-out | Single account, or implicit fan-out | | Transports | STDIO and Streamable HTTP /mcp | Usually STDIO only | | Guardrails | Confirmation gating, audit log, anti-spam limits, chat allow-list, untrusted-content marking | Minimal | | Distribution | Signed runtime bundles (no JDK), SBOM + provenance, GHCR image | Source install via pip/npx |

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 115 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:

| Profile | Surface | |---|---| | reader | Always non-mutating — safe for a first look | | inbox | Personal messages, drafts, media, contacts, privacy | | community-admin | Moderation, group/channel, permissions, bot commands | | research | Bounded account/public discovery and reading | | all | The full inventory (opt in deliberately) |

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

Features

• 115 MCP tools — messages, polls, read receipts, scheduled sends, chats, folders, invite-link administration, contacts, media, drafts, privacy, bot commands, detailed group permissions, profile, search, and account routing.
• TDLib via tdlight-java — real user accounts, not just the Bot API.
• Isolated multi-account mode — independent sessions, mandatory account selection, and optional per-key account scopes with no cross-account read fan-out.
• Safe by default — read-only tool surface, human approval for destructive actions (MCP_DESTRUCTIVE_APPROVAL, over the host or a loopback page), and task-focused profiles (reader/inbox/community-admin/research/all).
• Recoverable sends — optional idempotency keys and durable receipts for text, replies, files, voice, stickers, forwards and scheduled messages; see delivery recovery.
• Per-client permissions — a reviewed JSON file grants each client read, download, mutate, quota or policy actions on named accounts and chats; everything else is denied. See permissions.
• Answers an agent can trust — every tool publishes a typed output schema, errors carry a stable code with retry guidance, and exports and searches say when they are incomplete.
• Long-running work — compact inbox and conversation tools with response budgets, exports that resume after a restart, and a change journal that reports its own gaps.
• Two transports — STDIO for desktop clients and Streamable HTTP /mcp (Spring AI 2.0 / MCP SDK 2.0), with API-key auth; telegram-mcp daemon shares one local server between several clients.