Telegram Bot MCP

MCP (Multi-purpose Computing Platform) for working with Telegram Bot API. Provides functions for sending and receiving messages through Telegram bot.

Features

• Send text messages to chats
• Send media content (photos, documents, videos, audio)
• Create and send polls
• Get bot information
• Get updates (messages, events) from users
• Delete messages

Installation

git clone https://github.com/coderroleggg/telegram-bot-mcp
cd telegram-bot-mcp
uv venv
source .venv/bin/activate
uv pip install -e .

Connecting to Claude Desktop, Cursor

Add the telegram-bot block to your mcp.json or claude_desktop_config.json or completely replace the file content with:

{
    "mcpServers": {
        "telegram-bot": {
            "type": "stdio",
            "command": "uv",
            "args": [
                "run",
                "--directory",
                "/Users/yourusername/Downloads/telegram-bot-mcp", // path to the bot code folder
                "server"
            ],
            "name": "Telegram Bot API",
            "description": "MCP for working with Telegram Bot API. Send messages, media and work with bot.",
            "config": {
                "token": "YOUR_BOT_TOKEN_HERE"
            }
        }
    }
}

Available Functions

• sendMessage - send text message
• sendPhoto - send photo
• deleteMessage - delete message
• getMe - get bot information
• getUpdates - get new messages and events

Usage Examples

Sending a Message

response = mcp.call("sendMessage", {"chatId": "12345678", "text": "Hello, world!"})
print(response)

Getting Updates

updates = mcp.call("getUpdates", {})
for update in updates["updates"]:
    print(update)

Example Usage in Cursor

Here's how to use the Telegram Bot MCP in Cursor:

Result Message

Example of a message sent through the bot:

License

MIT

API Tools

initialize

Initializes configuration for Telegram Bot MCP.

Parameters:

• token: Your Telegram bot token obtained from @BotFather

sendMessage

Sends a text message to the specified chat.

Parameters:

• chatId: Chat ID where to send the message (string or number)
• text: Message text to send

sendPhoto

Sends a photo to the specified chat.

Parameters:

• chatId: Chat ID where to send the photo (string or number)
• photoUrl: Photo URL or path to local file
• caption: Photo caption (optional)

sendDocument

Sends a document to the specified chat.

Parameters:

• chatId: Chat ID where to send the document (string or number)
• documentUrl: Document URL or path to local file
• caption: Document caption (optional)
• filename: File name (optional)

sendVideo

Sends a video to the specified chat.

Parameters:

• chatId: Chat ID where to send the video (string or number)
• videoUrl: Video URL or path to local file
• caption: Video caption (optional)
• duration: Video duration in seconds (optional)
• width: Video width (optional)
• height: Video height (optional)

sendAudio

Sends audio to the specified chat.

Parameters:

• chatId: Chat ID where to send the audio (string or number)
• audioUrl: Audio URL or path to local file
• caption: Audio caption (optional)
• duration: Audio duration in seconds (optional)
• performer: Performer (optional)
• title: Track title (optional)

sendPoll

Sends a poll message to the specified chat.

Parameters:

• chatId: Chat ID where to send the poll (string or number)
• question: Poll question
• options: List of answer options (strings)
• isAnonymous: Whether the poll is anonymous (optional, default True)
• allowsMultipleAnswers: Whether multiple answers are allowed (optional, default False)

getMe

Gets information about the bot.

Parameters: none

getUpdates

Gets updates (messages, events) from Telegram Bot API.

Parameters:

• offset: ID of the first update to return (optional)
• limit: Maximum number of updates to return (optional, default 100)
• timeout: Timeout in seconds (optional, default 0)

deleteMessage

Deletes a message from the chat.

Parameters:

• chatId: Chat ID from which to delete the message (string or number)
• messageId: Message ID to delete (number)

How to Get chatId?

To get a chat or user ID, there are several ways:

1. Use the getUpdates tool and find the needed ID after sending a message to your bot

2. Use a bot like @userinfobot: send it a message, and it will return your ID

3. For group chats: add your bot to the group, send a message and use getUpdates to find the group ID

4. For channels:

   • First, add your bot as an administrator to the channel with permission to send messages
   • Forward any message from the channel to @userdatailsbot
   • The bot will return the channel ID (it will be negative and start with -100)
   • Use this ID as chatId when sending messages to the channel

Limitations

• Bot cannot start a conversation with a user first, the user must send a message to the bot first
• Bot can only send messages to chats where it is present
• Some file formats may be restricted by Telegram
• When sending local files, they must be accessible to the process in which MCP is running

Additional Information

For more information about Telegram Bot API:

• Official Telegram Bot API Documentation
• python-telegram-bot Documentation