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)

Related MCP server: MCP Telegram

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.

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.).