telegram-mcp
Provides access to Telegram in two modes: a personal bot for exchanging files and notes with the owner and sending messages/files, and read-only account access for listing chats, reading and searching messages, and downloading files without marking them as read.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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. |
|
Your account | Read and search your chats via Telethon. Reading does not mark messages as read. Sending works only to chats you list in |
|
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.txtConfigure
python setup.pyBot: create one with @BotFather (
/newbot), paste the token, then send/startto your bot. That chat becomes the only owner.Account: get
api_id/api_hashat 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.pyStart 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:
/revokein @BotFather, then runsetup.pyagain.
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:
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.targetMCP sessions: set
TG_MCP_EXTERNAL_POLLER=1so they never callgetUpdatesthemselves (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"}}'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_inboxowner_only: access control. Messages from anyone exceptowner_chat_idstop here (commands get "Это приватный бот.").commands: answers/help,/start,/status.store_in_inbox: saves everything else forbot_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 -vThey 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.pyFor 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Your Telegram, WhatsApp, Instagram, mail and calendar in Claude or ChatGPT. Never sends messages.
Hosted Telegram MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Free WhatsApp MCP server for ChatGPT and Claude: read and search chats, every send you approve.
Related MCP Servers
- AlicenseAqualityBmaintenanceRead-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.558 npmMIT
- AlicenseNot gradedqualityDmaintenanceA read-only Telegram MCP server that retrieves messages from your DMs, groups, and channels, enabling Claude to generate executive briefings from Telegram conversations.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants like Claude to read, search, and send messages through your personal Telegram account via MCP tools.MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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