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

telegram-mcp-server