telegram-mcp-connector

An MCP server that lets Claude (Claude Code, Claude Desktop) read and search your own Telegram account, and, if you turn it on, send messages from it.

It logs in as you over MTProto (via Telethon), not as a bot, so Claude sees the same chats you do.

Security. The session file gives full access to your Telegram account. It stays on your machine, in .data/ inside this folder, with mode 0600, and is never committed. Write access is off by default.

Tools

✋ These tools only exist when TG_ALLOW_WRITE=true.

A chat argument accepts a numeric id, @username, a t.me link, me (Saved Messages) or a chat title.

Related MCP server: Telegram MCP Server

Install

Everything installs inside this folder: the virtualenv in .venv/, the uv cache in .uv-cache/ (see uv.toml), and the session and config in .data/. Deleting the folder removes all of it. Requires uv and Python ≥ 3.11.

git clone https://github.com/nitatsuu/telegram-mcp-connector.git
cd telegram-mcp-connector
uv sync

1. Get API credentials

Go to https://my.telegram.org, open API development tools, and create an app (any name). You get an api_id and an api_hash.

2. Log in (once)

uv run telegram-mcp-connector login

It asks for api_id/api_hash (saved to .data/.env), then your phone number, the code Telegram sends you, and your 2FA password if you use one. The device shows up as telegram-mcp-connector under Telegram → Settings → Devices.

Check the result:

uv run telegram-mcp-connector status

3. Connect to Claude

Claude Code:

claude mcp add telegram -s user -- uv run --directory "$(pwd)" telegram-mcp-connector

Claude Desktop: add this to claude_desktop_config.json, using absolute paths:

{
  "mcpServers": {
    "telegram": {
      "command": "/opt/homebrew/bin/uv",
      "args": ["run", "--directory", "/path/to/telegram-mcp-connector", "telegram-mcp-connector"]
    }
  }
}

Then ask Claude something like "what did I miss in Telegram today?" or "find where Alex sent the contract".

Enabling writes

Edit .data/.env:

TG_ALLOW_WRITE=true
# ids and/or @usernames, comma-separated. "me" = Saved Messages, "*" = any chat.
TG_SEND_ALLOWLIST=me, @alice, -1001234567890

Restart Claude (or the MCP server) for the change to take effect. Get chat ids from list_chats.

Why the allowlist: messages Claude reads are written by other people. A message could contain instructions aimed at an AI. The server tells Claude to ignore such instructions, Claude asks before calling write tools, and the allowlist adds a hard limit on top of both.

Configuration

Values are read from environment variables, then from <data dir>/.env. Environment variables take priority.

Uninstall

uv run telegram-mcp-connector logout   # revokes the session on Telegram's side
claude mcp remove telegram -s user     # if added to Claude Code
cd .. && rm -rf telegram-mcp-connector

You can also revoke the session from Telegram → Settings → Devices.

Notes

• Only one process can use the session at a time (it is an SQLite file). If login or status reports database is locked, close Claude first.

• Telegram rate limits: short flood waits are slept through automatically. This tool is meant for personal use, not bulk messaging.

Development

uv run pytest

License

MIT