Telegram MCP Server MCP Server

Name: Telegram MCP Server MCP Server
Author: io.github.tolboy

io.github.tolboy/telegram-mcp-tdlib

Repository Registry

What is the Telegram MCP Server MCP server?

Local-first TDLib Telegram MCP server with 110 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

Claude Desktop

~/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.15.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>"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "telegram-mcp-tdlib": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/tolboy/telegram-mcp-tdlib:1.15.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>"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "telegram-mcp-tdlib": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/tolboy/telegram-mcp-tdlib:1.15.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>"
      }
    }
  }
}

VS Code

.vscode/mcp.json

{
  "servers": {
    "telegram-mcp-tdlib": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/tolboy/telegram-mcp-tdlib:1.15.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>"
      }
    }
  }
}

Claude Code

claude mcp add telegram-mcp-tdlib --env TDLIB_API_ID=<YOUR_TDLIB_API_ID> --env TDLIB_API_HASH=<YOUR_TDLIB_API_HASH> --env TDLIB_PHONE_NUMBER=<YOUR_TDLIB_PHONE_NUMBER> --env TDLIB_AUTH_CODE=<YOUR_TDLIB_AUTH_CODE> --env TDLIB_2FA_PASSWORD=<YOUR_TDLIB_2FA_PASSWORD> --env MCP_READ_ONLY=<YOUR_MCP_READ_ONLY> --env MCP_TOOL_PROFILE=<YOUR_MCP_TOOL_PROFILE> -- docker run -i --rm ghcr.io/tolboy/telegram-mcp-tdlib:1.15.0-stdio