telegram-mcp — read-only Telegram MCP server with a per-chat allowlist

An MCP server that lets an assistant read only the chats you list by hand, and nothing else — no private conversations, no chats you forgot about, no writes at all.

Why another Telegram MCP server

Existing servers expose your whole account. A Telegram MTProto session sees every dialog, and none of the popular servers can narrow that down to a set of chats: in chigwell/telegram-mcp that is open issue #116. Read-only modes exist, but "read-only" there still means "read everything you have".

If you want an assistant in your work chats without handing it your family group, that gap is the whole point of this server:

Related MCP server: telemcp

Security model

• Closed list. allowed_chats.json is the single source of truth. Anything not in it is denied — by id, by alias and by title.

• Denial happens before the network. Every handler asks the allowlist first, so a forbidden chat never becomes a Telegram request. There is a test that asserts exactly this over real stdio.

• The answer is re-checked. After Telegram resolves an entity, its real id is matched against the allowlist again — a renamed or substituted chat cannot slip through.

• No write path. There is no send_message to disable: the code does not contain one. All five tools are annotated readOnlyHint.

• Text is data, not instructions. Message texts, names and titles are sanitised (zero-width characters, bidi overrides, control characters) and truncated, and the tool descriptions tell the model to treat them as untrusted input.

• The allowlist lives outside the installation. By default it is read from ~/.config/telegram-mcp/allowed_chats.json, so real chat ids never end up next to the code — which is what makes running straight from a git URL safe.

Tools

A chat is referenced by its alias (team), its exact title, or its id.

Requirements

• Python 3.10+

• uv (recommended — no clone or virtualenv needed)

• A Telegram API application: https://my.telegram.org/apps → api_id and api_hash

Setup

1. Issue a session string

export TELEGRAM_API_ID=… TELEGRAM_API_HASH=…
uvx --from git+https://github.com/nskondratev/telegram-mcp telegram-mcp login

Telethon asks for your phone number, the login code and the 2FA password — you type them yourself, they are never stored. The command prints a session string.

⚠️ The session string grants full access to your Telegram account. Treat it like a password: never commit it, never paste it into a chat. It lives in your MCP client config (for Claude Code, ~/.claude.json), which is not in git.

2. Build the allowlist

export TELEGRAM_SESSION_STRING=…
uvx --from git+https://github.com/nskondratev/telegram-mcp telegram-mcp dialogs --filter acme

The output is id kind title per dialog. Put the ones you want into ~/.config/telegram-mcp/allowed_chats.json, using allowed_chats.example.json as the template:

{
  "chats": [
    { "alias": "team",   "id": -1001111111111, "title": "Team chat", "note": "main work chat" },
    { "alias": "alerts", "id": -1002222222222, "title": "Alerts",    "note": "monitoring" }
  ]
}

Duplicate aliases or ids are a startup error, not a warning. dialogs --json prints a ready-made skeleton you can edit.

3. Connect the server

Claude Code:

claude mcp add telegram -s user \
  -e TELEGRAM_API_ID=… \
  -e TELEGRAM_API_HASH=… \
  -e TELEGRAM_SESSION_STRING=… \
  -e TG_ALLOWED_CHATS_FILE=$HOME/.config/telegram-mcp/allowed_chats.json \
  -- uvx --from git+https://github.com/nskondratev/telegram-mcp telegram-mcp serve

Any MCP client works — the transport is stdio. The equivalent JSON:

{
  "mcpServers": {
    "telegram": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/nskondratev/telegram-mcp",
        "telegram-mcp", "serve"
      ],
      "env": {
        "TELEGRAM_API_ID": "…",
        "TELEGRAM_API_HASH": "…",
        "TELEGRAM_SESSION_STRING": "…",
        "TG_ALLOWED_CHATS_FILE": "/home/you/.config/telegram-mcp/allowed_chats.json"
      }
    }
  }
}

4. Verify

uvx --from git+https://github.com/nskondratev/telegram-mcp telegram-mcp check

check reads every allowed chat and then tries a chat that is not on the list, so a broken allowlist shows up here rather than mid-conversation.

Configuration

Every command also accepts --allowlist PATH. Editing the allowlist takes effect when the MCP client restarts the server.

For convenience, login, dialogs and check fall back to the env block of a Telegram MCP server in ~/.claude.json when the variables are not exported — so they keep working right after the server is wired into Claude Code.

Development

git clone https://github.com/nskondratev/telegram-mcp
cd telegram-mcp
uv run --extra dev pytest      # 54 tests, no account or network required
uv run --extra dev ruff check .

The tests replace Telethon with a fake, so the allowlist logic, the sanitiser and the refusal path are all covered offline. tests/test_server_integration.py additionally starts the real server over stdio and asserts that a forbidden chat is rejected before any Telegram credentials are even looked at.

Layout: core.py — allowlist and sanitising; handlers.py — the five read operations; client.py — a Telethon wrapper that warms the dialog cache; server.py — MCP tool definitions; cli.py — serve / login / dialogs / check.

The installable distribution is named telegram-allowlist-mcp; the import package and the command are both telegram_mcp / telegram-mcp.

License

MIT