Telegram MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with the Telegram Bot API. This server enables AI assistants like Claude to interact with Telegram, including support for sending messages, managing media, and handling interactive callback buttons.

Features

• Rich Messaging: Send text messages with Markdown, HTML, or plain text formatting
• Media Support: Send photos, videos, and documents
• Message Management: Forward, delete, and retrieve chat information
• Interactive Callbacks: Full support for inline keyboards and callback queries
• Update Polling: Receive incoming messages and callback queries
• Type-Safe: Built with TypeScript and Zod for robust input validation
• MCP Compatible: Works with Claude Desktop, Cursor, and other MCP clients

Installation

Prerequisites

• Node.js 18 or higher
• A Telegram Bot Token (get one from @BotFather)

From npm

npm install -g telegram-mcp

From Source

git clone https://github.com/YOUR_USERNAME/telegram-mcp.git
cd telegram-mcp
npm install
npm run build

Configuration

Getting a Telegram Bot Token

1. Open Telegram and search for @BotFather
2. Send /newbot and follow the instructions
3. Copy the bot token provided by BotFather
4. Set it as an environment variable: TELEGRAM_BOT_TOKEN

Claude Desktop Configuration

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "telegram-mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your-bot-token-here"
      }
    }
  }
}

Cursor Configuration

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "telegram-mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your-bot-token-here"
      }
    }
  }
}

Available Tools

send_message

Send a text message to a Telegram chat.

Parameters:

• chat_id (string|number, required): Chat ID to send message to
• text (string, required): Text message to send
• parse_mode (string, optional): "Markdown", "MarkdownV2", or "HTML"
• disable_notification (boolean, optional): Send message silently

Example:

Send a message "Hello from Claude!" to chat ID 123456789

send_photo

Send a photo to a Telegram chat.

Parameters:

• chat_id (string|number, required): Chat ID
• photo (string, required): Photo file path or URL
• caption (string, optional): Photo caption
• parse_mode (string, optional): Caption formatting mode

send_document

Send a document/file to a Telegram chat.

Parameters:

• chat_id (string|number, required): Chat ID
• document (string, required): Document file path or URL
• caption (string, optional): Document caption

send_video

Send a video to a Telegram chat.

Parameters:

• chat_id (string|number, required): Chat ID
• video (string, required): Video file path or URL
• caption (string, optional): Video caption

forward_message

Forward a message from one chat to another.

Parameters:

• chat_id (string|number, required): Destination chat ID
• from_chat_id (string|number, required): Source chat ID
• message_id (number, required): Message ID to forward

delete_message

Delete a message from a chat.

Parameters:

• chat_id (string|number, required): Chat ID
• message_id (number, required): Message ID to delete

get_chat

Get information about a chat.

Parameters:

• chat_id (string|number, required): Chat ID

get_updates

Receive incoming updates (messages, callback queries, etc.).

Parameters:

• offset (number, optional): Identifier of the first update to return
• limit (number, optional): Number of updates to retrieve (1-100)
• timeout (number, optional): Timeout in seconds for long polling

send_inline_keyboard

Send a message with inline keyboard buttons.

Parameters:

• chat_id (string|number, required): Chat ID
• text (string, required): Message text
• inline_keyboard (array, required): Array of button rows
• parse_mode (string, optional): Message formatting mode

Example:

Send a message with buttons:
- Text: "Choose an option:"
- Buttons: [
    [{"text": "Option 1", "callback_data": "opt1"}],
    [{"text": "Option 2", "callback_data": "opt2"}]
  ]

answer_callback_query

Answer a callback query from an inline keyboard button.

Parameters:

• callback_query_id (string, required): Unique identifier for the query
• text (string, optional): Notification text (0-200 characters)
• show_alert (boolean, optional): Show as alert instead of notification

edit_message_text

Edit the text of an existing message.

Parameters:

• chat_id (string|number, required): Chat ID
• message_id (number, required): Message ID to edit
• text (string, required): New text
• parse_mode (string, optional): Formatting mode

edit_message_reply_markup

Edit the inline keyboard of an existing message.

Parameters:

• chat_id (string|number, required): Chat ID
• message_id (number, required): Message ID to edit
• inline_keyboard (array, required): New inline keyboard

Usage Examples

Basic Message Sending

Send "Hello, World!" to my Telegram chat 123456789

Interactive Callback Workflow

1. Send a message with inline keyboard:
   - Text: "What's your favorite color?"
   - Buttons: [
       [{"text": "Red", "callback_data": "color_red"}],
       [{"text": "Blue", "callback_data": "color_blue"}]
     ]

2. Get updates to receive callback queries

3. When user clicks a button, answer the callback query:
   - callback_query_id: (from update)
   - text: "You selected Red!"

4. Edit the original message to show the selection:
   - Update text to "You chose: Red"

Sending Media

Send a photo from https://example.com/image.jpg to chat 123456789 with caption "Check this out!"

Finding Your Chat ID

To find your chat ID:

1. Send a message to your bot
2. Use the get_updates tool to retrieve updates
3. Look for the chat.id field in the response

Alternatively, use @userinfobot on Telegram.

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Run production build
npm start

Troubleshooting

"TELEGRAM_BOT_TOKEN environment variable is required"

Make sure you've set the TELEGRAM_BOT_TOKEN in your MCP configuration.

"400 Bad Request: chat not found"

Verify the chat ID is correct. The bot must have access to the chat (user must have started the bot or bot must be added to the group).

Callback queries not working

1. Make sure to call answer_callback_query after receiving a callback query
2. Check that callback_data is set on your inline keyboard buttons
3. Use get_updates to retrieve callback queries

Security Notes

• Never share your bot token publicly
• Use environment variables to store sensitive credentials
• Be cautious with chat IDs - validate access controls in your application
• Consider implementing rate limiting for production use

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions:

• Open an issue on GitHub
• Check the Telegram Bot API documentation
• Review the MCP documentation