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+
• uv for dependency management and running the server
• A Telegram bot application with a bot token (Telegram Bot API)

Installation

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

Configuration

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_updates to 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_webhook instead of polling with get_updates.

Tools

Update this list to match what main.py actually implements.

Tool	Description
get_bot_info	Fetch the bot's own user info
get_webhook_info / set_webhook / delete_webhook	Manage the bot's webhook
get_updates	Poll for new messages/events (alternative to a webhook)
get_my_commands / set_my_commands	Fetch or register the bot's slash commands
send_message / edit_message_text / delete_message	Send, edit, or delete a text message
send_photo / send_video / send_audio / send_document / send_voice	Send media to a chat
send_poll / stop_poll	Create a poll or close one and return results
pin_chat_message / unpin_chat_message	Pin or unpin a message
set_message_reaction	React to a message with an emoji
answer_callback_query	Respond to an inline keyboard button press
get_chat	Fetch info about a chat/channel
get_chat_administrators	List a chat's administrators
get_chat_member	Get a specific user's membership status in a chat
ban_chat_member / unban_chat_member	Moderation actions
set_chat_title / set_chat_description	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 via send_photo
• Pin the top-priority alert with pin_chat_message, unpin it later with unpin_chat_message
• Correct a typo or update a price target on a sent alert with edit_message_text instead of re-sending

Community engagement

• Run a daily sentiment poll with send_poll, close it with stop_poll, and post the tally with send_message
• Auto-react to confirm an alert was received, using set_message_reaction
• Send 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 with answer_callback_query, then reply with send_message
• Register commands like /subscribe, /mute, /stats with set_my_commands and drive their logic off get_updates

Moderation & access control

• Ban a user spamming or scraping paid content with ban_chat_member, reverse with unban_chat_member
• Gate sensitive commands by checking get_chat_administrators or get_chat_member first
• Remove spam or leaked-content messages with delete_message

Housekeeping / setup

• Rotate the channel name/description with set_chat_title / set_chat_description
• Switch between polling (get_updates) and push delivery (set_webhook/get_webhook_info) when moving from local dev to hosted
• Sanity-check the bot's identity and permissions with get_bot_info before deploying a new flow

Running standalone

uv run --project /absolute/path/to/telegram-mcp python /absolute/path/to/telegram-mcp/main.py

The 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 .env file 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.).