Telegram MCP for Claude Desktop: Setup & Config

What you can do with Telegram in Claude Desktop

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

• Review chat history and prepare responses.
• Search unread messages across configured accounts.
• Schedule messages or organize Telegram folders.

Before you start: Telegram in Claude Desktop

• 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 Desktop configuration

1. Choose Claude Desktop configuration scope

   For Telegram MCP, open macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json. Merge under mcpServers via Settings → Developer → Edit Config when available.

2. Add Telegram MCP to Claude Desktop

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

3. Check Telegram MCP in Claude Desktop

   Telegram MCP: Fully quit and reopen Claude Desktop; check developer diagnostics.

{
  "mcpServers": {
    "telegram-mcp": {
      "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 Desktop

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

send_file

When Claude Desktop requests send_file from Telegram, review the action before approving it.

Send a local file from an allowed filesystem root.

download_media

When Claude Desktop requests download_media from Telegram, review the action before approving it.

Download Telegram media within configured file-access boundaries.

upload_file

When Claude Desktop requests upload_file from Telegram, review the action before approving it.

Upload a local file using configured allowed roots.

send_voice

When Claude Desktop requests send_voice from Telegram, review the action before approving it.

Send a voice note from a permitted file path.

send_sticker

When Claude Desktop requests send_sticker from Telegram, review the action before approving it.

set_profile_photo

When Claude Desktop requests set_profile_photo from Telegram, review the action before approving it.

edit_chat_photo

When Claude Desktop requests edit_chat_photo from Telegram, review the action before approving it.

Telegram: full stored tool descriptions

Troubleshooting Telegram in Claude Desktop

• Fully quit and reopen Claude Desktop for Telegram MCP. If uv is missing, check the desktop process's PATH, which may differ from your terminal.
• In Claude Desktop's Telegram MCP entry, check TELEGRAM_API_HASH, TELEGRAM_API_ID, TELEGRAM_EXPOSED_TOOLS, TELEGRAM_SESSION_STRING. Keep secrets out of shared screenshots and repositories.
• Telegram MCP uses stdio here: Claude Desktop 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 Desktop troubleshooting lives in the /clients/claude-desktop guide.

Frequently asked questions