Telegram MCP Server

Name: Telegram MCP Server
Author: tolboy

tolboy

Get started Repository

TDLib-powered Telegram MCP server for JVM/Kotlin. Full client access for AI agents.

Setup

Choose your client, copy the config, then fill in any required environment variables.

Add to Cursor Add to VS Code

claude mcp add telegram-server-tolboy --env TDLIB_API_ID='<TDLIB_API_ID>' --env TDLIB_API_HASH='<TDLIB_API_HASH>' --env TDLIB_PHONE_NUMBER='<TDLIB_PHONE_NUMBER>' --env TDLIB_AUTH_CODE='<TDLIB_AUTH_CODE>' --env 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.3-stdio

~/.codex/config.toml

[mcp_servers.telegram-server-tolboy]
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.3-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>" }

# codex mcp add telegram-server-tolboy --env TDLIB_API_ID='<TDLIB_API_ID>' --env TDLIB_API_HASH='<TDLIB_API_HASH>' --env TDLIB_PHONE_NUMBER='<TDLIB_PHONE_NUMBER>' --env TDLIB_AUTH_CODE='<TDLIB_AUTH_CODE>' --env 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.3-stdio

~/.cursor/mcp.json

{
  "mcpServers": {
    "telegram-server-tolboy": {
      "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.3-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>"
      }
    }
  }
}

.vscode/mcp.json

{
  "servers": {
    "telegram-server-tolboy": {
      "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.3-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>"
      }
    }
  }
}

~/.gemini/settings.json

{
  "mcpServers": {
    "telegram-server-tolboy": {
      "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.3-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>"
      }
    }
  }
}

claude_desktop_config.json

{
  "mcpServers": {
    "telegram-server-tolboy": {
      "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.3-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>"
      }
    }
  }
}

.trae/mcp.json

{
  "mcpServers": {
    "telegram-server-tolboy": {
      "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.3-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>"
      }
    }
  }
}

Environment variables

TDLIB_API_ID
TDLIB_API_HASH
TDLIB_PHONE_NUMBER
TDLIB_AUTH_CODE
TDLIB_2FA_PASSWORD

Replace the placeholders with your own credentials and keep them out of version control.

Setup

Environment variables

Related