Skip to main content
Glama

Telegram MCP

An MCP (Model Context Protocol) server that exposes Telegram bot actions as tools for LLM clients (e.g. Claude Desktop, Claude Code).

Telegram MCP screenshot

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.

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

Available Tools

28 tools
answer_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

    B3.2/5.0

    Scored across 28 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      MCP 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
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      20
      MIT