Telegram MCP
Provides tools for interacting with the Telegram Bot API, enabling AI agents to send and edit messages, manage media, polls, and chat administration, as well as moderate groups and handle webhooks.
Telegram MCP
An MCP (Model Context Protocol) server that exposes Telegram bot actions as tools for LLM clients (e.g. Claude Desktop, Claude Code).

Requirements
Python 3.10+
uvfor dependency management and running the serverA Telegram bot application with a bot token (Telegram Bot API)
Related MCP server: MCP Telegram
Installation
git clone https://github.com/EncryptMan/telegram-mcp telegram-mcp
cd telegram-mcp
uv syncConfiguration
The server reads its Telegram bot token from the TELEGRAM_BOT_TOKEN environment variable.
Add the server to your MCP client config (e.g. claude_desktop_config.json):
{
"mcpServers": {
"telegram": {
"command": "uv",
"args": [
"run",
"--project",
"/absolute/path/to/telegram-mcp",
"python",
"/absolute/path/to/telegram-mcp/main.py"
],
"env": {
"TELEGRAM_BOT_TOKEN": "your-bot-token-here"
}
}
}
}Restart your MCP client after editing the config so it picks up the new server.
Bot permissions
Make sure the bot is set up with the following, depending on which tools you use:
Privacy mode disabled via @BotFather if you need
get_updatesto see all messages in a group, not just commands and replies to the bot.Admin rights in the chat/channel for any moderation or management tool:
ban_chat_member,unban_chat_member,delete_message,pin_chat_message,unpin_chat_message,set_chat_title,set_chat_description.A webhook URL with a valid HTTPS certificate if you use
set_webhookinstead of polling withget_updates.
Tools
Update this list to match what
main.pyactually implements.
Tool | Description |
| Fetch the bot's own user info |
| Manage the bot's webhook |
| Poll for new messages/events (alternative to a webhook) |
| Fetch or register the bot's slash commands |
| Send, edit, or delete a text message |
| Send media to a chat |
| Create a poll or close one and return results |
| Pin or unpin a message |
| React to a message with an emoji |
| Respond to an inline keyboard button press |
| Fetch info about a chat/channel |
| List a chat's administrators |
| Get a specific user's membership status in a chat |
| Moderation actions |
| Update a chat/channel's title or description |
Example automations
Some concrete tasks this server can drive, e.g. for a trading-alerts community:
Alert distribution
Push formatted signals to a channel with
send_message, with a chart viasend_photoPin the top-priority alert with
pin_chat_message, unpin it later withunpin_chat_messageCorrect a typo or update a price target on a sent alert with
edit_message_textinstead of re-sending
Community engagement
Run a daily sentiment poll with
send_poll, close it withstop_poll, and post the tally withsend_messageAuto-react to confirm an alert was received, using
set_message_reactionSend weekly performance recaps as a file with
send_document
Interactive bot menus
Build inline buttons (e.g. "Mute this ticker"); receive the press via
get_updates/webhook, acknowledge it withanswer_callback_query, then reply withsend_messageRegister commands like
/subscribe,/mute,/statswithset_my_commandsand drive their logic offget_updates
Moderation & access control
Ban a user spamming or scraping paid content with
ban_chat_member, reverse withunban_chat_memberGate sensitive commands by checking
get_chat_administratorsorget_chat_memberfirstRemove spam or leaked-content messages with
delete_message
Housekeeping / setup
Rotate the channel name/description with
set_chat_title/set_chat_descriptionSwitch between polling (
get_updates) and push delivery (set_webhook/get_webhook_info) when moving from local dev to hostedSanity-check the bot's identity and permissions with
get_bot_infobefore deploying a new flow
Running standalone
uv run --project /absolute/path/to/telegram-mcp python /absolute/path/to/telegram-mcp/main.pyThe server communicates over stdio, so it's meant to be launched by an MCP client rather than run interactively.
Security notes
Never commit your
TELEGRAM_BOT_TOKEN— keep it in your MCP client config or a local.envfile that's gitignored.Scope the bot's admin rights in each chat to only what these tools need; avoid granting full admin unless required.
License
Add a license of your choice (MIT, Apache-2.0, etc.).
Available Tools
28 toolsanswer_callback_queryB
Answer a callback query (from inline buttons).
Inputs: callback_query_id (required), text, show_alert.
ban_chat_memberC
Ban a user from a chat.
Inputs: chat_id (required), user_id (required).
delete_messageC
Delete a message from a chat.
Inputs: chat_id (required), message_id (required).
delete_webhookA
Delete the bot's webhook.
Inputs: no named parameters.
edit_message_textC
Edit the text of a message.
Inputs: text (required), chat_id (required), message_id (required).
get_bot_infoA
Fetch the bot's own user info.
Inputs: no named parameters.
get_chatB
Fetch info about a chat/channel by ID.
Inputs: chat_id (required).
get_chat_administratorsB
List the administrators of a chat.
Inputs: chat_id (required).
get_chat_memberB
Get a specific user's membership status in a chat.
Inputs: chat_id (required), user_id (required).
get_my_commandsA
Fetch the bot's currently registered commands.
Inputs: no named parameters.
get_updatesC
Fetch updates (messages, commands, etc.) for the bot.
Inputs: limit, offset.
get_webhook_infoB
Get information about the bot's webhook.
Inputs: no named parameters.
pin_chat_messageC
Pin a message in a chat.
Inputs: chat_id (required), message_id (required), disable_notification.
send_audioB
Send an audio file to a chat. audio can be a URL or a file_id.
Inputs: audio (required), chat_id (required), caption.
send_documentB
Send a document/file to a chat. document can be a URL or a file_id.
Inputs: chat_id (required), document (required), caption.
send_messageC
Send a message to a chat.
Inputs: text (required), chat_id (required).
send_photoB
Send a photo to a chat. photo can be a URL or a file_id already known to Telegram.
Inputs: photo (required), chat_id (required), caption.
send_pollC
Send a poll to a chat.
Inputs: chat_id (required), options (required), question (required), is_anonymous.
send_videoB
Send a video to a chat. video can be a URL or a file_id.
Inputs: video (required), chat_id (required), caption.
send_voiceB
Send a voice note to a chat. voice can be a URL or a file_id.
Inputs: voice (required), chat_id (required).
set_chat_descriptionC
Update a chat/channel's description.
Inputs: chat_id (required), description (required).
set_chat_titleB
Rename a chat/channel.
Inputs: title (required), chat_id (required).
set_message_reactionB
React to a message with an emoji (default: thumbs up).
Inputs: chat_id (required), message_id (required), emoji.
set_my_commandsA
Register bot commands so Telegram shows them in the UI.
commands is a list of {"command": "start", "description": "..."} dicts.
Inputs: commands (required).
set_webhookB
Set a webhook URL for the bot to receive updates.
Inputs: url (required).
stop_pollC
Close a poll and return the final results.
Inputs: chat_id (required), message_id (required).
unban_chat_memberB
Unban a user from a chat.
Inputs: chat_id (required), user_id (required).
unpin_chat_messageA
Unpin a message (or the most recent pinned message if message_id is omitted).
Inputs: chat_id (required), message_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Each tool targets a distinct Telegram API action, such as sending specific media types, managing messages, or handling chat members. There is no meaningful overlap between tools, even the media senders are clearly differentiated by type.
All tool names follow a consistent snake_case verb_noun pattern (e.g., send_message, get_chat_member, set_webhook). The verbs are descriptive and the objects are clear, making the naming predictable and easy to navigate.
With 28 tools, the server exceeds the 25-tool threshold the rubric associates with 'too many'. While Telegram's API is broad, many of these tools cover niche media types and admin actions, making the surface feel heavy rather than focused.
The tool set covers the core Telegram bot lifecycle: sending, editing, deleting, pinning, reacting, and polling, plus webhook and chat administration. Minor gaps exist, such as forward_message and edit_message_caption, but agents can work around these by resending or recreating content.
Maintenance
Related MCP Connectors
Unofficial Telegram MCP server — read, search, reply and react in your own Telegram account.
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Hosted Telegram MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
MemberPass MCP — manage projects, plans, members, payments, and analytics for Telegram creators.
Related MCP Servers
- MIT
- AlicenseNot gradedqualityBmaintenanceTelegram MTProto-based MCP server with 19 tools for reading, searching, sending, forwarding, and summarizing messages3MIT
- FlicenseAqualityDmaintenanceMCP server that gives MCP clients access to a personal Telegram account. It can read chats, search messages, download media, and send messages or files while keeping credentials local.7-
- AlicenseAqualityCmaintenanceEnables local, privacy-first control of a personal Telegram account through MCP, using TDLib to read chats, send and reply to messages, search, transfer files, and interact with approved inline buttons.20MIT