Telegram MCP Server

MCP server · by tolboy

Communication Docker v1.17.2

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

View source ↗ Generate config for multiple servers More servers

Install

Run one of the commands below, then pick your client in the next section.

Docker
docker run -i --rm ghcr.io/tolboy/telegram-mcp-tdlib:1.17.2-stdio

Setup by client

Pick your client — the config below is generated for this server (local stdio).

claude_desktop_config.json

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

Format verified against the official Claude Desktop docs ↗.

terminal

claude mcp add --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> telegram-mcp-tdlib -- docker run -i --rm ghcr.io/tolboy/telegram-mcp-tdlib:1.17.2-stdio

Format verified against the official Claude Code docs ↗.

.cursor/mcp.json

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

Format verified against the official Cursor docs ↗.

.vscode/mcp.json

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

Format verified against the official VS Code docs ↗.

mcp_config.json

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

Format verified against the official Windsurf docs ↗.

Environment variables

Defined in the server's official registry manifest. Required secrets are shown as <YOUR_…> placeholders in the configs above.

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

About this server

Distributed as Docker, listed under Communication. Review our MCP security guide before granting access to real data.

Frequently asked questions

How do I install Telegram MCP Server?

Run the install command shown above, then paste the config for your client (Claude Desktop, Claude Code, Cursor, VS Code or Windsurf) into its MCP settings and restart the client.

Is Telegram MCP Server free to use?

The MCP server itself is free to install. The source is public on https://github.com/tolboy/telegram-mcp-tdlib. Any third-party service it calls may require its own API key and account.

Which clients support Telegram MCP Server?

Any MCP-compatible client can use it, including Claude Desktop, Claude Code, Cursor, VS Code, Windsurf and custom agents.

Add this badge

Publish this server? Link back with a badge on your README or site — copy either snippet.

Markdown

[![Listed on MCPNav](https://mcpnav.net/badge/telegram-mcp-tdlib.svg)](https://mcpnav.net/server/telegram-mcp-tdlib/)

HTML

<a href="https://mcpnav.net/server/telegram-mcp-tdlib/"><img src="https://mcpnav.net/badge/telegram-mcp-tdlib.svg" alt="Listed on MCPNav" height="20"></a>