mcp-telegram

MCP (Model Context Protocol) server that connects Claude Desktop, Claude Code or Cursor to your personal Telegram account. Ask your AI assistant in plain language:

«Что мне написали за утро? Суммаризируй рабочий чат.» «Найди сообщение, где Иван скидывал адрес офиса.» «Ответь Ивану, что буду в 15:00.»

The assistant picks the right tool, your account does the work.

Tools

Tool	What it does
list_chats	Recent chats, optionally only ones with unread messages
read_chat	Last N messages of a chat (by name, @username or id)
search	Full-text search in one chat or across all chats
send_message	Send a text message (only when you explicitly ask)

Built on the official MCP Python SDK (FastMCP) and Telethon (MTProto — your real account, not a bot; bots can't read your own chats).

Setup

1. Get Telegram API credentials (2 minutes, one time): go to my.telegram.org → API development tools → create an app → copy api_id and api_hash.

2. Install and log in:

git clone https://github.com/StepanCEO/mcp-telegram
cd mcp-telegram
pip install -r requirements.txt
cp .env.example .env          # put api_id/api_hash there
python -m mcp_telegram.login  # one-time: phone number + code from Telegram

The login creates a session file (~/.mcp-telegram.session); after that the server runs non-interactively.

3. Wire it into your client.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "telegram": {
      "command": "python",
      "args": ["-m", "mcp_telegram"],
      "cwd": "C:/path/to/mcp-telegram"
    }
  }
}

Claude Code:

claude mcp add telegram -- python -m mcp_telegram

Cursor (.cursor/mcp.json) — same shape as Claude Desktop.

Restart the client — the telegram tools appear automatically.

Security notes

• The session file grants full access to your account — it stays on your machine, is never sent anywhere, and is .gitignored. Treat it like a password.
• send_message is described to the model as "use only when the user explicitly asks", and MCP clients ask for your confirmation before tool calls by default.
• This is your personal account: respect Telegram's terms — no spam, no mass messaging.

Tests

pip install pytest pytest-asyncio
pytest

Tests run against a fake Telethon client — no network or real account needed. They cover unread filtering, message ordering, search, sending, and chat-id parsing.

Project structure

mcp_telegram/
├── server.py    # MCP tools (FastMCP, stdio transport)
├── service.py   # Telegram operations + formatting (testable core)
├── login.py     # one-time interactive sign-in
└── config.py    # .env settings
tests/
└── test_service.py

License

MIT