Skip to main content
Glama
telegram-mcp

telegram-mcp

by Spleps

telegram-mcp

A small, self-hosted MCP server that gives Claude (or any MCP client) access to Telegram in two safe modes:

Mode

What it does

Tools

Personal bot

Exchange files and notes with your own bot. The bot talks only to its owner; messages from anyone else are ignored.

bot_inbox, bot_download, bot_send_message, bot_send_file

Your account

Read and search your chats via Telethon. Reading does not mark messages as read. Sending works only to chats you list in config.json → "send_allowed_chats": [chat_id, ...], the chat must be given by exact id or @username, and every send is logged to sent.jsonl. There are no edit / delete tools.

tg_list_chats, tg_read, tg_search, tg_download, tg_send_message, tg_send_files

Both modes are optional: configure one or both.

Use cases

  • Forward photos of a lab manual to the bot → "take the photos from the bot and write the report".

  • "What was posted in my study group chat this week?"

  • "Send the finished report to my Telegram."

Related MCP server: telegram-briefing-mcp

Install

Requires Python 3.10+.

git clone https://github.com/Spleps/telegram-mcp.git
cd telegram-mcp
pip install -r requirements.txt

Configure

python setup.py
  1. Bot: create one with @BotFather (/newbot), paste the token, then send /start to your bot. That chat becomes the only owner.

  2. Account: get api_id / api_hash at my.telegram.org → API development tools. Log in by scanning a QR code (Telegram → Settings → Devices → Link Desktop Device). If you use a cloud password (2FA), a small dialog asks for it.

Secrets are stored next to the script in config.json and account.session. On Windows the setup restricts both files to the current user. They are listed in .gitignore: never share them. The session file gives full access to your account.

Register in Claude Code

claude mcp add --scope user telegram -- python /path/to/telegram-mcp/server.py

Start a new Claude session and the bot_* / tg_* tools appear. Downloaded files go to ~/Downloads/Telegram MCP.

Revoke access

  • Account: Telegram → Settings → Devices → terminate the session.

  • Bot: /revoke in @BotFather, then run setup.py again.

Bot commands

While the MCP server is running (i.e. a Claude session is open), the bot long-polls in the background and answers instantly:

  • /help: what the bot can do

  • /status: how many messages are waiting for Claude

When no session is open, messages are not lost: Telegram keeps undelivered updates for 24 hours and the bot picks them up on the next start.

Run 24/7 on a server

To keep the bot answering when no Claude session is open, run the poller as a service and let MCP sessions only read the inbox:

  1. Poller (bot only, no MCP): python server.py --poll. It exits on a fatal error, so run it under a supervisor. Example systemd unit:

    [Unit]
    Description=Telegram personal bot poller
    Wants=network-online.target
    After=network-online.target
    
    [Service]
    User=youruser
    WorkingDirectory=/home/youruser/telegram-mcp
    ExecStart=/home/youruser/telegram-mcp/.venv/bin/python server.py --poll
    Restart=always
    RestartSec=10
    
    [Install]
    WantedBy=multi-user.target
  2. MCP sessions: set TG_MCP_EXTERNAL_POLLER=1 so they never call getUpdates themselves (two pollers fight with HTTP 409):

    claude mcp add-json --scope user telegram '{"type":"stdio","command":"/home/youruser/telegram-mcp/.venv/bin/python","args":["/home/youruser/telegram-mcp/server.py"],"env":{"TG_MCP_EXTERNAL_POLLER":"1"}}'
  3. From another computer, run the same server over SSH (key login), so there is still only one copy of the secrets:

    claude mcp add --scope user telegram -- ssh -o BatchMode=yes youruser@server 'TG_MCP_EXTERNAL_POLLER=1 /home/youruser/telegram-mcp/.venv/bin/python /home/youruser/telegram-mcp/server.py'

    Downloaded files then land on the server (~/Downloads/Telegram MCP).

Only one process may use the account session at a time: Telegram can revoke a session used from two connections at once. server.py takes a lock on account.lock, and a second process gets a clear error instead.

How updates are handled

Every incoming message goes through a middleware chain in server.py:

owner_only -> commands -> store_in_inbox
  • owner_only: access control. Messages from anyone except owner_chat_id stop here (commands get "Это приватный бот.").

  • commands: answers /help, /start, /status.

  • store_in_inbox: saves everything else for bot_inbox.

Add your own middleware as def mw(ctx, nxt) and put it into MIDDLEWARES.

Tests

Offline tests (no network, no real config) cover the middleware chain, access control, commands, pull_updates with a fake Telegram API, and the file helpers:

python -m unittest discover -s tests -v

They also run on GitHub Actions on every push.

Notes

  • Bot API limits: download ≤ 20 MB, upload ≤ 50 MB.

  • Setup prompts are in Russian.

License

MIT

Optional private-chat auto-replies

auto_reply.py uses a separate Telethon session and replies only to explicitly allowlisted private users. Bots, groups, channels and the owner are ignored. The Copilot CLI generates text without shell, file or MCP tools; replies include an automated-reply prefix and are rate-limited. An empty allowlist replies to nobody.

Add an auto_reply object to your local, ignored config.json:

{
  "auto_reply": {
    "enabled": true,
    "chats": [],
    "owner_name": "Account owner",
    "cooldown_seconds": 20,
    "max_per_hour": 30
  }
}

Set chats to the user IDs you explicitly want to receive replies. Install Copilot CLI, log in, then create the separate Telegram session:

.venv/bin/python auto_reply.py --login
.venv/bin/python auto_reply.py

For systemd, telegram-auto-reply@.service is a template for installations at /home/<user>/Projects/telegram-mcp. Install it under /etc/systemd/system/ and select the service instance telegram-auto-reply@<user>.service. Adapt the paths if your account has another home directory. Configs, sessions and reply logs stay local and must never be committed.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Read-only Telegram access for Claude and other MCP hosts. Provides tools to list chats, read recent messages, and download media from your own Telegram account without needing an api_id/api_hash.
      5
      58 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A read-only Telegram MCP server that retrieves messages from your DMs, groups, and channels, enabling Claude to generate executive briefings from Telegram conversations.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants like Claude to read, search, and send messages through your personal Telegram account via MCP tools.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to interact with a personal Telegram account via MCP, offering tools for reading and searching chats, summarizing unread messages, sending and editing messages, handling files and voice transcripts, and managing groups and channels, with read-only mode by default.
      Apache 2.0