Telegram MCP for Claude Code: Setup & Config

What you can do with Telegram in Claude Code

Use Telegram account workflows from MCP with multi-account routing and configurable tool exposure.

• Schedule messages or organize Telegram folders.
• Manage groups, channels, and member permissions.
• Send or download media within approved file roots.

Before you start: Telegram in Claude Code

• Python 3.10+
• uv for this source-checkout configuration
• Clone of chigwell/telegram-mcp with uv sync completed
• Telegram API credentials and an authorized session
• An MCP client

Replace the checkout path. Generate a session using the repository session generator before starting. Do not install the unrelated telegram-mcp package from PyPI. File tools need explicitly allowed roots; read-only exposure is not an account sandbox.

Telegram Claude Code configuration

1. Choose Claude Code configuration scope

   For Telegram MCP, open Project scope: .mcp.json at the repository root. Project JSON: merge into mcpServers; user scope: use the CLI.

2. Add Telegram MCP to Claude Code

   Use the telegram-mcp entry below in mcpServers. Keep Telegram MCP's documented stdio connection fields and your other Claude Code entries.

3. Check Telegram MCP in Claude Code

   Telegram MCP: Inspect claude mcp list and /mcp status.

{
  "mcpServers": {
    "telegram-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "TELEGRAM_API_ID": "<Telegram application API ID>",
        "TELEGRAM_API_HASH": "<Telegram application API hash>",
        "TELEGRAM_SESSION_STRING": "<Authorized Telegram session string>",
        "TELEGRAM_EXPOSED_TOOLS": "<Optional all or read-only tool exposure>"
      }
    }
  }
}

claude mcp add-json --scope project 'telegram-mcp' '{"type":"stdio","command":"uv","args":["--directory","/full/path/to/telegram-mcp","run","main.py"],"env":{"TELEGRAM_API_ID":"<Telegram application API ID>","TELEGRAM_API_HASH":"<Telegram application API hash>","TELEGRAM_SESSION_STRING":"<Authorized Telegram session string>","TELEGRAM_EXPOSED_TOOLS":"<Optional all or read-only tool exposure>"}}'

Telegram tools available to Claude Code

Telegram's stored tool list documents 7 tools; compare it with Claude Code's connected tool list, because the stored list is not a live check.

send_file

For Telegram's send_file, review the permission request and arguments in Claude Code before approval.

download_media

For Telegram's download_media, review the permission request and arguments in Claude Code before approval.

upload_file

For Telegram's upload_file, review the permission request and arguments in Claude Code before approval.

Upload a local file using configured allowed roots.

send_voice

For Telegram's send_voice, review the permission request and arguments in Claude Code before approval.

Send a voice note from a permitted file path.

send_sticker

For Telegram's send_sticker, review the permission request and arguments in Claude Code before approval.

Send a sticker using an allowed local path.

set_profile_photo

For Telegram's set_profile_photo, review the permission request and arguments in Claude Code before approval.

edit_chat_photo

For Telegram's edit_chat_photo, review the permission request and arguments in Claude Code before approval.

Change a chat photo using a permitted local file.

Telegram: full stored tool descriptions

Troubleshooting Telegram in Claude Code

• If Telegram MCP fails to start, check uv, the working directory, and Claude Code's selected scope; inspect claude mcp list and /mcp.
• Telegram MCP: check TELEGRAM_API_HASH, TELEGRAM_API_ID, TELEGRAM_EXPOSED_TOOLS, TELEGRAM_SESSION_STRING; keep credentials out of shared .mcp.json.
• Telegram MCP uses stdio here: Claude Code must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Session credentials grant normal Telegram account authority.
• Known limitation: The PyPI package with the same name is unrelated.
• Known limitation: File tools require allowed-root configuration.
• General Claude Code troubleshooting lives in the /clients/claude-code guide.

Frequently asked questions