telegram-mcp-server

Bigchef-dev/telegram-mcp-server

3.2

If you are the rightful owner of telegram-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Telegram MCP Server is an implementation that provides tools for interacting with the Telegram Bot API, allowing AI assistants to send messages and retrieve bot information programmatically.

Tools
9
Resources
0
Prompts
0

Telegram MCP Server

smithery badge

An MCP server implementation that provides tools for interacting with the Telegram Bot API. This service allows AI assistants to send messages and retrieve bot information programmatically.

Tools

The Telegram MCP Service provides the following tools for interacting with the Telegram Bot API:

get_bot_info

Retrieves basic information about the bot.

  • No parameters required
  • Returns a User object containing bot information

send_message

Sends a message to a specified chat.

  • chatId: Unique identifier for the target chat (can be string or number)
  • text: Text of the message to be sent
  • params (optional): Additional parameters for the message (e.g., parse_mode, reply_markup, etc.)

get_updates

Receives incoming updates using long polling.

  • params (optional): Object containing optional parameters:
    • offset (optional): Identifier of the first update to be returned
    • limit (optional): Limits the number of updates to be retrieved (1-100)
    • timeout (optional): Timeout in seconds for long polling
    • allowed_updates (optional): Array of update types to receive
  • Returns an array of Update objects containing various types of updates:
    • Messages and edited messages
    • Channel posts
    • Business messages
    • Inline queries
    • Callback queries
    • Shipping queries
    • Pre-checkout queries
    • Polls and poll answers
    • Chat member updates
    • Chat join requests
    • Chat boosts

forward_message

Forwards messages of any kind. Service messages and messages with protected content can't be forwarded.

  • chatId: Unique identifier for the target chat or username of the target channel (in the format @channelusername)
  • fromChatId: Unique identifier for the chat where the original message was sent (or channel username in the format @channelusername)
  • messageId: Message identifier in the chat specified in from_chat_id
  • params (optional): Object containing optional parameters:
    • message_thread_id (optional): Unique identifier for the target message thread (topic) of the forum; for forum supergroups only
    • video_start_timestamp (optional): New start timestamp for the forwarded video in the message
    • disable_notification (optional): Sends the message silently. Users will receive a notification with no sound.
    • protect_content (optional): Protects the contents of the forwarded message from forwarding and saving
  • Returns the sent Message object on success

pin_chat_message

Adds a message to the list of pinned messages in a chat. In private chats and channel direct messages chats, all non-service messages can be pinned. Conversely, the bot must be an administrator with the 'can_pin_messages' right or the 'can_edit_messages' right to pin messages in groups and channels respectively.

  • chatId: Unique identifier for the target chat or username of the target channel (in the format @channelusername)
  • messageId: Identifier of a message to pin
  • businessConnectionId (optional): Unique identifier of the business connection on behalf of which the message will be pinned
  • disableNotification (optional): Pass True if it is not necessary to send a notification to all chat members about the new pinned message. Notifications are always disabled in channels and private chats.
  • Returns True on success

unpin_chat_message

Removes a message from the list of pinned messages in a chat. In private chats and channel direct messages chats, all messages can be unpinned. Conversely, the bot must be an administrator with the 'can_pin_messages' right or the 'can_edit_messages' right to unpin messages in groups and channels respectively.

  • chatId: Unique identifier for the target chat or username of the target channel (in the format @channelusername)
  • messageId (optional): Identifier of the message to unpin. If not specified, the most recent pinned message (by sending date) will be unpinned
  • businessConnectionId (optional): Unique identifier of the business connection on behalf of which the message will be unpinned
  • Returns True on success

unpin_all_chat_messages

Clears the list of pinned messages in a chat. In private chats and channel direct messages chats, no additional rights are required to unpin all pinned messages. Conversely, the bot must be an administrator with the 'can_pin_messages' right or the 'can_edit_messages' right to unpin all pinned messages in groups and channels respectively.

  • chatId: Unique identifier for the target chat or username of the target channel (in the format @channelusername)
  • Returns True on success

getChat

Gets up-to-date information about the chat. Returns detailed chat information including settings, permissions, and metadata.

  • chat_id: Unique identifier for the target chat or username of the target supergroup or channel (in the format @channelusername)
  • Returns a ChatFullInfo object containing comprehensive chat details:
    • Basic info: id, type, title, username, description
    • Settings: permissions, slow mode delay, message auto-delete time
    • Features: protected content, hidden members, aggressive anti-spam
    • Optional info: photo, location, sticker set, linked chat
    • Business info: intro, location, opening hours (for business accounts)
    • Personal info: birthdate, bio, emoji status (for private chats)

sendPoll

Sends a native poll to a chat. Returns the sent Message containing the poll on success. Note that polls can't be sent to channel direct messages chats.

  • chat_id: Unique identifier for the target chat or username of the target channel (in the format @channelusername)
  • question: Poll question, 1-300 characters
  • options: Array of exactly 2 to 10 answer options (required). Each option must have text of 1-100 characters with optional formatting
  • type (optional): Poll type, "quiz" or "regular" (defaults to "regular")
  • is_anonymous (optional): True if the poll should be anonymous (defaults to True)
  • allows_multiple_answers (optional): True if multiple answers are allowed (defaults to False, ignored for quiz polls)
  • correct_option_id (optional): 0-based identifier of the correct answer (required for quiz polls)
  • explanation (optional): Text shown for incorrect quiz answers, 0-200 characters
  • open_period (optional): Poll duration in seconds, 5-600 (can't be used with close_date)
  • close_date (optional): Unix timestamp when poll closes (can't be used with open_period)
  • is_closed (optional): True to immediately close the poll (useful for previews)
  • disable_notification (optional): Send silently
  • protect_content (optional): Protect message from forwarding/saving
  • reply_parameters (optional): Reply to another message
  • reply_markup (optional): Additional interface options (keyboards, etc.)
  • Additional options: business_connection_id, message_thread_id, question_parse_mode, question_entities, explanation_parse_mode, explanation_entities, allow_paid_broadcast, message_effect_id

Configuration

Environment Variables

You need to set up the following environment variables:

TELEGRAM_BOT_TOKEN=your_bot_token
MCP_MODE=stdio
PORT=3001
  • TELEGRAM_BOT_TOKEN: Your bot token (required)
  • MCP_MODE: Server mode - stdio for MCP clients or web for HTTP/SSE API (defaults to stdio)
  • PORT: Port for web mode (defaults to 3001)

You can get your bot token by talking to @BotFather on Telegram and creating a new bot.

Creating a new bot

Use the /newbot command to create a new bot. @BotFather will ask you for a name and username, then generate an authentication token for your new bot.

The name of your bot is displayed in contact details and elsewhere.

The username is a short name, used in search, mentions and t.me links. Usernames are 5-32 characters long and not case sensitive – but may only include Latin characters, numbers, and underscores. Your bot's username must end in 'bot', like 'tetris_bot' or 'TetrisBot'.

The token is a string, like 123456:my-secret, which is required to authorize the bot and send requests to the Bot API. Keep your token secure and store it safely, it can be used by anyone to control your bot.

Unlike the bot's name, the username cannot be changed later – so choose it carefully. When sending a request to api.telegram.org, remember to prefix the word 'bot' to your token.

Development

Standard MCP Mode (stdio)

npm install
npm run build
npx @modelcontextprotocol/inspector node dist/index.js

Open http://127.0.0.1:6274 to set up the environment and interact with the tools.

Web Mode (HTTP/SSE)

npm install
npm run build
MCP_MODE=web PORT=3001 node dist/index.js

The server will be available at http://localhost:3001 with Server-Sent Events support.

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.