telegram-mcp

Local MCP server for working with Telegram through a userbot session.

Gives agents (Claude Code and any other MCP clients) a set of tools for reading and sending messages, searching, working with chats, contacts, and media — on behalf of your Telegram account, via Telethon (MTProto, not Bot API).

Works via stdio only and keeps the session locally in encrypted form — the only traffic going out is to Telegram servers.

Why

The Bot API can do little and requires a bot. A userbot session is a full-fledged client: it sees all your dialogs, history, group members, can search across all of Telegram, send files and video notes, and add reactions. This server neatly wraps such capabilities into 28 MCP tools so an agent can work with Telegram the same way you do from the app.

Related MCP server: telegram-mcp

Features

• Dialogs and chats — list of dialogs with unread counts, info about chat/channel/user (including bio/description), folders, joining and leaving groups.

• Messages — history with pagination, search (global and per chat), sending, editing, deleting, forwarding, pinning, reactions, marking as read.

• Media — sending files (photo/video/document/voice/video note; for video dimensions and duration are filled in via ffprobe), downloading attachments.

• Contacts and people — your own profile, address book, resolving @username/phone/link to an entity, global search for people and channels, group members.

• Login — by phone number (code + 2FA) or by QR code, directly from tools or from the CLI.

Security

A userbot session is full access to the account, therefore:

• Stdio only. The server does not open a network port: communication with the MCP client goes through standard input/output. Only traffic to Telegram leaves the machine.

• The session is encrypted on disk (Fernet). The session string is the key to the account, and it is placed on disk only encrypted, in ~/.telegram-mcp/session.enc. The key is taken from TELEGRAM_MCP_ENC_KEY or generated once in ~/.telegram-mcp/enc.key with permissions 0600.

• Read-only mode. Running with TELEGRAM_MCP_READONLY=1 disables all mutating tools (sending/editing/deleting/forwarding/joining/reactions) — convenient for monitoring and auditing.

• Actions on your behalf. Everything the server sends/deletes happens on behalf of the account owner. Keep this in mind when giving an agent access.

• The first login is best done via the CLI telegram-mcp-login: the code and 2FA password are entered in the terminal and do not pass through the agent's context.

Installation

Requires Python ≥ 3.10.

git clone git@github.com:bssth/telegram-mcp.git
cd telegram-mcp
python -m venv .venv

# Windows:
.venv\Scripts\pip install -e ".[speed,qr]"
# Linux/macOS:
# .venv/bin/pip install -e ".[speed,qr]"

Optional extras:

For correct dimensions/duration of sent video, ffmpeg (the ffprobe utility) in PATH is desirable — optional, video is sent without it too.

Setup and login

1. Get api_id / api_hash at https://my.telegram.org → API development tools.

2. Copy .env.example to .env and fill it in:

   TELEGRAM_API_ID=1234567
   TELEGRAM_API_HASH=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   # пусто = ключ шифрования сгенерируется в ~/.telegram-mcp/enc.key
   TELEGRAM_MCP_ENC_KEY=

3. Log in to the account (once):

   telegram-mcp-login

   It will ask for the number → the code from Telegram → the 2FA password (if enabled), or offer QR login. The encrypted session will be placed in ~/.telegram-mcp/session.enc, and from then on the server starts already authorized.

   Login is also possible without the CLI — via the login_send_code / login_complete / login_qr tools. But the CLI is safer: secrets do not enter the agent's context.

Connecting to Claude Code

.mcp.json in the project (or the user MCP client config):

{
  "mcpServers": {
    "telegram": {
      "command": "D:\\dev\\telegram-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "telegram_mcp"],
      "env": {
        "TELEGRAM_API_ID": "1234567",
        "TELEGRAM_API_HASH": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "TELEGRAM_MCP_ENC_KEY": "<ваш Fernet-ключ>"
      }
    }
  }
}

• command — the path to python from your venv (the package is installed in it).

• The env block can be omitted if the variables are already set in the system environment or in ~/.telegram-mcp/.env.

• You can check without a client via the inspector: npx @modelcontextprotocol/inspector <path>\python.exe -m telegram_mcp.

Tools

The chat argument almost everywhere is a string: a numeric id, @username, a link t.me/..., a phone number, or me / self for Saved Messages.

Login

Chats

Messages

Media

Contacts and people

✱ — mutating tool, disabled by the TELEGRAM_MCP_READONLY=1 flag.

Configuration (environment variables)

Variables are read from the environment and from .env in the current directory.

How it works

src/telegram_mcp/
  __main__.py     # `python -m telegram_mcp` → stdio-сервер; флаг --self-check
  app.py          # сборка MCP-приложения: lifespan (один клиент на процесс) + тулзы
  client.py       # рантайм: подключение, вход, разрешение пиров, флуд-хендлинг
  session.py      # шифрование StringSession (Fernet) и хранение на диске
  serialize.py    # Telethon-объекты → компактный JSON для агента
  errors.py       # человекочитаемые ошибки входа/лимитов
  login.py        # интерактивный CLI первого входа
  tools/          # auth, dialogs, messages, media, contacts

A single shared TelegramClient is started in the server lifespan (inside its event loop, as Telethon requires) and reused by all tools. Peers are resolved with dialog cache warming, Telegram errors are translated into readable text, and the session between runs is read from the encrypted file.

Development

.venv\Scripts\python -m telegram_mcp --self-check   # собрать и показать список тулз
.venv\Scripts\pytest                                # офлайн-тесты (без сети и Telegram)

Tests do not touch the network: they cover session encryption, link parsing in resolve, serialization, config, the read-only mode guard, and registration of all tools via the real MCP stdio protocol.

License

MIT.