telegram-api-mcp

Overview

This MCP server provides complete coverage of Telegram Bot API v9.6 with all 169 methods exposed as tools. It includes sophisticated features like rate limiting (global and per-chat), circuit breaker pattern, retry with backoff, and meta-mode for context efficiency. The server uses TypeScript with Zod validation for robust parameter checking, implements security measures like token masking and path traversal protection, and maintains minimal dependencies (only 2). The codebase follows a clean architecture with declarative method registration, making it easy to extend and maintain.

Try asking AI

After installing, here are 5 things you can ask your AI assistant:

• telegram_find

  Search Telegram Bot API methods by keyword or category

  Try:Search for methods related to pollsTry:Find all chat management methods
• telegram_call

  Call any Telegram Bot API method by name with JSON parameters

  Try:Send a message to chatTry:Create a new forum topicTry:Get bot information
• sendMessage

  Send text messages to a chat

  Try:Send 'Hello!' to my channelTry:Send a message with formatting
• sendPhoto

  Send photos to a chat

  Try:Send a photo to groupTry:Upload an image from my computer
• sendPoll

  Send polls to a chat

  Try:Create a yes/no poll in my channelTry:Send a quiz with correct answer
• getChat

  Get information about a chat

  Try:Get details about my groupTry:Check if chat exists
• banChatMember

  Ban a user from a chat

  Try:Ban user from my groupTry:Remove member permanently
• forwardMessage

  Forward messages between chats

  Try:Forward a message to my channelTry:Share message to another group
• editMessageText

  Edit text messages

  Try:Correct a typo in my messageTry:Update a message with new information
• getMe

  Get information about the bot

  Try:Show my bot detailsTry:Check bot username and ID
• setMyCommands

  Set bot commands in the menu

  Try:Add /help and /start commandsTry:Update bot command menu
• sendSticker

  Send stickers to a chat

  Try:Send a sticker reactionTry:Share an animated sticker

Comparable tools

Installation

claude mcp add telegram -- npx telegram-api-mcp -e TELEGRAM_BOT_TOKEN=your_token

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["telegram-api-mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your_token_from_botfather"
      }
    }
  }
}

git clone https://github.com/timoncool/telegram-api-mcp.git
cd telegram-api-mcp
npm install && npm run build
TELEGRAM_BOT_TOKEN=your_token node dist/index.js

FAQ

What is meta-mode and why use it?

Meta-mode uses only 2 tools (telegram_find and telegram_call) instead of 169, saving ~99% of context tokens. This is useful for long conversations where maintaining context for all 169 tools would be too expensive.

How does rate limiting work?

The server implements token bucket rate limiting with two levels: global (30 req/sec by default) and per-chat (20 msg/min by default). These limits match Telegram's official requirements and prevent API abuse.

Compare telegram-api-mcp with