Telegram MCP Server for Claude Cowork

This project exposes a Telegram account to Claude Cowork through MCP. It uses Telethon to connect to Telegram and FastMCP to expose tools that Claude can call over stdio, which is the most reliable way to connect local MCP servers to Claude Desktop and Cowork.

Features

• List recent chats and unread counts
• Look up chat metadata
• Search chats by name
• Read recent messages
• Send a message or reply
• Search messages globally or inside a chat
• List contacts
• Mark chats as read

Files

• telegram_mcp_server.py: the MCP server
• telegram_login.py: one-time login helper
• requirements.txt: Python dependencies

Prerequisites

• Python 3.11+ or 3.12+
• A Telegram API ID and API hash from my.telegram.org
• Claude Desktop / Claude Cowork with local MCP enabled

Install

cd telegram-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configure Telegram credentials

Create ~/.telegram-mcp/config.json:

{
  "api_id": "123456",
  "api_hash": "your_api_hash",
  "phone": "+15551234567"
}

You can also provide the same values through environment variables:

• TELEGRAM_API_ID
• TELEGRAM_API_HASH
• TELEGRAM_PHONE

One-time login

Run:

~/.telegram-mcp/venv/bin/python3 telegram_login.py

If you are using the repo-local virtualenv instead:

.venv/bin/python3 telegram_login.py

Telegram will prompt for your login code and any 2FA password. On success it stores the session at ~/.telegram-mcp/session.session and also exports a lock-free runtime session to ~/.telegram-mcp/session.string. The MCP server prefers the string session so Claude, Codex, and automations can use Telegram at the same time without SQLite lock errors.

Connect it to Claude Cowork

Add this entry to:

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "telegram": {
      "command": "/ABSOLUTE/PATH/TO/.venv/bin/python3",
      "args": [
        "/ABSOLUTE/PATH/TO/telegram_mcp_server.py"
      ]
    }
  }
}

If you are using the shared environment from ~/.telegram-mcp/venv, the entry would look like:

{
  "mcpServers": {
    "telegram": {
      "command": "/Users/you/.telegram-mcp/venv/bin/python3",
      "args": [
        "/path/to/telegram-mcp-server/telegram_mcp_server.py"
      ]
    }
  }
}

Then fully restart Claude Desktop. Cowork should discover the Telegram tools on startup.

Available tools

• list_chats(limit=30)
• get_chat_info(chat_id)
• search_chats(query, limit=10)
• read_messages(chat_id, limit=20)
• send_message(chat_id, text, reply_to_message_id=0)
• search_messages(query, chat_id=0, limit=20, sender_name="")
• get_contacts(limit=50)
• mark_as_read(chat_id)

Optional SSE debugging mode

For local debugging only, you can run the server over SSE:

TELEGRAM_MCP_TRANSPORT=sse \
TELEGRAM_MCP_HOST=127.0.0.1 \
TELEGRAM_MCP_PORT=8457 \
.venv/bin/python3 telegram_mcp_server.py

This is useful for testing transport behavior, but Claude Cowork should use the stdio setup above.

Troubleshooting

If Claude does not show the tools:

• Verify the paths in claude_desktop_config.json are absolute
• Restart Claude Desktop completely
• Re-run telegram_login.py if the Telegram session expired
• Confirm your config file or environment variables contain api_id and api_hash

If you see database is locked:

• Re-run telegram_login.py to refresh ~/.telegram-mcp/session.string
• Restart Claude Desktop or open a fresh Codex session so new MCP processes use the string session

If authentication fails:

• Make sure your phone number includes the country code
• Make sure you are using credentials from my.telegram.org, not a bot token

Security notes

Do not commit:

• ~/.telegram-mcp/config.json
• ~/.telegram-mcp/session.session
• ~/.telegram-mcp/session.string
• any exported logs containing message content