Telegram MCP Server

by tolboyio.github.tolboy/telegram-mcp-tdlibv1.17.0

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

9Dockerstdioofficial registry

context tax

queued

security

queued

cold start

queued

freshness

Active11d ago

Install Telegram MCP server

claude mcp add telegram-mcp-tdlib -e TDLIB_API_ID='<tdlib-api-id>' -e TDLIB_API_HASH='<tdlib-api-hash>' -e TDLIB_PHONE_NUMBER='<tdlib-phone-number>' -e TDLIB_AUTH_CODE='<tdlib-auth-code>' -e TDLIB_2FA_PASSWORD='<tdlib-2fa-password>' -- docker run -i --rm -e TDLIB_API_ID -e TDLIB_API_HASH -e TDLIB_PHONE_NUMBER -e TDLIB_AUTH_CODE -e TDLIB_2FA_PASSWORD ghcr.io/tolboy/telegram-mcp-tdlib:1.17.0-stdio

{
  "mcpServers": {
    "telegram-mcp-tdlib": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TDLIB_API_ID",
        "-e",
        "TDLIB_API_HASH",
        "-e",
        "TDLIB_PHONE_NUMBER",
        "-e",
        "TDLIB_AUTH_CODE",
        "-e",
        "TDLIB_2FA_PASSWORD",
        "ghcr.io/tolboy/telegram-mcp-tdlib:1.17.0-stdio"
      ],
      "env": {
        "TDLIB_API_ID": "<tdlib-api-id>",
        "TDLIB_API_HASH": "<tdlib-api-hash>",
        "TDLIB_PHONE_NUMBER": "<tdlib-phone-number>",
        "TDLIB_AUTH_CODE": "<tdlib-auth-code>",
        "TDLIB_2FA_PASSWORD": "<tdlib-2fa-password>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project).

{
  "mcpServers": {
    "telegram-mcp-tdlib": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TDLIB_API_ID",
        "-e",
        "TDLIB_API_HASH",
        "-e",
        "TDLIB_PHONE_NUMBER",
        "-e",
        "TDLIB_AUTH_CODE",
        "-e",
        "TDLIB_2FA_PASSWORD",
        "ghcr.io/tolboy/telegram-mcp-tdlib:1.17.0-stdio"
      ],
      "env": {
        "TDLIB_API_ID": "<tdlib-api-id>",
        "TDLIB_API_HASH": "<tdlib-api-hash>",
        "TDLIB_PHONE_NUMBER": "<tdlib-phone-number>",
        "TDLIB_AUTH_CODE": "<tdlib-auth-code>",
        "TDLIB_2FA_PASSWORD": "<tdlib-2fa-password>"
      }
    }
  }
}

Settings → Developer → Edit Config (claude_desktop_config.json), then restart.

{
  "servers": {
    "telegram-mcp-tdlib": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TDLIB_API_ID",
        "-e",
        "TDLIB_API_HASH",
        "-e",
        "TDLIB_PHONE_NUMBER",
        "-e",
        "TDLIB_AUTH_CODE",
        "-e",
        "TDLIB_2FA_PASSWORD",
        "ghcr.io/tolboy/telegram-mcp-tdlib:1.17.0-stdio"
      ],
      "env": {
        "TDLIB_API_ID": "<tdlib-api-id>",
        "TDLIB_API_HASH": "<tdlib-api-hash>",
        "TDLIB_PHONE_NUMBER": "<tdlib-phone-number>",
        "TDLIB_AUTH_CODE": "<tdlib-auth-code>",
        "TDLIB_2FA_PASSWORD": "<tdlib-2fa-password>"
      }
    }
  }
}

Add to .vscode/mcp.json in your workspace.

{
  "mcpServers": {
    "telegram-mcp-tdlib": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TDLIB_API_ID",
        "-e",
        "TDLIB_API_HASH",
        "-e",
        "TDLIB_PHONE_NUMBER",
        "-e",
        "TDLIB_AUTH_CODE",
        "-e",
        "TDLIB_2FA_PASSWORD",
        "ghcr.io/tolboy/telegram-mcp-tdlib:1.17.0-stdio"
      ],
      "env": {
        "TDLIB_API_ID": "<tdlib-api-id>",
        "TDLIB_API_HASH": "<tdlib-api-hash>",
        "TDLIB_PHONE_NUMBER": "<tdlib-phone-number>",
        "TDLIB_AUTH_CODE": "<tdlib-auth-code>",
        "TDLIB_2FA_PASSWORD": "<tdlib-2fa-password>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json.

Configuration

Variable	Required	Secret	Description
TDLIB_API_ID	yes	—	Telegram API ID from my.telegram.org
TDLIB_API_HASH	yes	yes	Telegram API hash from my.telegram.org
TDLIB_PHONE_NUMBER	—	yes	Telegram phone number; omit after preparing a persisted session when using QR authentication
TDLIB_AUTH_CODE	—	yes	One-time Telegram login code for a fresh headless container
TDLIB_2FA_PASSWORD	—	yes	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

Freshness

Active — last maintenance signal 11d ago. The newest of the signals below sets the band.

Last commit (default branch)
2026-09-29 · 11d ago · GitHub
Latest release
2026-09-29 · 11d ago · GitHub · v1.17.0
Package published
no data · npm/PyPI
Registry entry updated
2026-09-29 · 11d ago · official registry · v1.17.0

FAQ

›How do I install the Telegram MCP server in Claude Code?

Run: claude mcp add telegram-mcp-tdlib -e TDLIB_API_ID='<tdlib-api-id>' -e TDLIB_API_HASH='<tdlib-api-hash>' -e TDLIB_PHONE_NUMBER='<tdlib-phone-number>' -e TDLIB_AUTH_CODE='<tdlib-auth-code>' -e TDLIB_2FA_PASSWORD='<tdlib-2fa-password>' -- docker run -i --rm -e TDLIB_API_ID -e TDLIB_API_HASH -e TDLIB_PHONE_NUMBER -e TDLIB_AUTH_CODE -e TDLIB_2FA_PASSWORD ghcr.io/tolboy/telegram-mcp-tdlib:1.17.0-stdio. For Cursor, VS Code, Claude Desktop and Windsurf, use the install tabs above.

›Does Telegram require an API key?

Yes. It expects TDLIB_API_ID, TDLIB_API_HASH, TDLIB_PHONE_NUMBER, TDLIB_AUTH_CODE, TDLIB_2FA_PASSWORD, of which 4 are secrets.

›Can I use Telegram as a remote (hosted) MCP server?

No hosted endpoint is published; it runs locally over stdio.

›Is Telegram in the official MCP registry?

Yes, as io.github.tolboy/telegram-mcp-tdlib.