Telegram MCP Server MCP Server

io.github.tolboy/telegram-mcp-tdlib

Repository Registry

What is the Telegram MCP Server MCP server?

Local-first TDLib Telegram MCP server with 115 tools, account isolation and production guardrails.

How to install Telegram MCP Server

Copy-paste configuration for popular MCP clients.

transport: stdio

Config generated by PluginBench — verify against the source before use.

Environment / auth

TDLIB_API_ID
required
Telegram API ID from my.telegram.org
TDLIB_API_HASH
required
secret
Telegram API hash from my.telegram.org
TDLIB_PHONE_NUMBER
secret
Telegram phone number; omit after preparing a persisted session when using QR authentication
TDLIB_AUTH_CODE
secret
One-time Telegram login code for a fresh headless container
TDLIB_2FA_PASSWORD
secret
Telegram 2FA password when the account requires it
MCP_READ_ONLY
Keep true for safe first use
MCP_TOOL_PROFILE
Tool surface: reader, inbox, community-admin, research, or all

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "telegram-mcp-tdlib": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/tolboy/telegram-mcp-tdlib:1.17.0-stdio"
      ],
      "env": {
        "TDLIB_API_ID": "<YOUR_TDLIB_API_ID>",
        "TDLIB_API_HASH": "<YOUR_TDLIB_API_HASH>",
        "TDLIB_PHONE_NUMBER": "<YOUR_TDLIB_PHONE_NUMBER>",
        "TDLIB_AUTH_CODE": "<YOUR_TDLIB_AUTH_CODE>",
        "TDLIB_2FA_PASSWORD": "<YOUR_TDLIB_2FA_PASSWORD>",
        "MCP_READ_ONLY": "<YOUR_MCP_READ_ONLY>",
        "MCP_TOOL_PROFILE": "<YOUR_MCP_TOOL_PROFILE>"
      }
    }
  }
}