🧠 Telegram Bot MCP Server

A powerful Model Context Protocol (MCP) server for seamless Telegram Bot API integration with intelligent message splitting, comprehensive error handling, and NPX support.

✨ Key Features

• 🔄 Intelligent Message Splitting: Automatically handles Telegram's 4096 character limit while preserving word boundaries and formatting
• 🛡️ Comprehensive Error Handling: Detailed error reporting with context, error codes, and debugging information
• 📦 NPX Support: Run directly with npx telegram-bot-mcp-server - no installation required
• 🔧 Easy Integration: Simple MCP client configuration for AI assistants
• 📝 Rich API Coverage: Complete Telegram Bot API functionality including messaging, user management, and bot configuration

🚀 Quick Start

Option 1: NPX (Recommended)

# Run directly without installation
npx telegram-bot-mcp-server

Option 2: NPM Installation

# Install globally
npm install -g telegram-bot-mcp-server

# Or install locally
npm install telegram-bot-mcp-server

📋 Prerequisites

1. Node.js 18+: Download here
2. Telegram Bot Token: Get one from @BotFather

Getting Your Bot Token

1. Open Telegram and search for @BotFather
2. Start a conversation and run: /newbot
3. Follow the prompts to name your bot
4. Copy the API token provided

🔧 MCP Client Configuration

Add this configuration to your MCP client (Claude Desktop, etc.):

{
  "mcpServers": {
    "telegram_bot": {
      "command": "npx",
      "args": ["telegram-bot-mcp-server"],
      "env": {
        "TELEGRAM_BOT_API_TOKEN": "your_bot_token_here"
      }
    }
  }
}

Alternative Configurations

Using global installation:

{
  "mcpServers": {
    "telegram_bot": {
      "command": "telegram-bot-mcp-server",
      "env": {
        "TELEGRAM_BOT_API_TOKEN": "your_bot_token_here"
      }
    }
  }
}

Using local installation:

{
  "mcpServers": {
    "telegram_bot": {
      "command": "node",
      "args": ["./node_modules/.bin/telegram-bot-mcp-server"],
      "env": {
        "TELEGRAM_BOT_API_TOKEN": "your_bot_token_here"
      }
    }
  }
}

🛠️ Available Tools

📨 Messaging Tools

send-message

Send text messages with automatic splitting for long content.

• Features: Intelligent message splitting, word boundary preservation
• Input: chatId (string), text (string)
• Auto-splitting: Messages over 4096 characters are automatically split

send-photo

Send photos with captions, handling long captions automatically.

• Features: Long caption splitting, multiple message support
• Input: chatId (string), media (string), text (optional string)

🖼️ send-photo

Send a photo with an optional caption.

• Input:
  • chatId: Target chat ID or username
  • media: File ID, URL, or uploaded file
  • text (optional): Caption for the photo

🔨 kick-chat-member

Ban a user from a group, supergroup, or channel.

• Input:
  • chatId: Target chat
  • userId: User to ban

♻️ un-ban-chat-member

Unban a previously banned user from a chat.

• Input:
  • chatId: Target chat
  • userId: User to unban

🧾 get-chat

Fetch full chat metadata and details.

• Input:
  • chatId: Target chat

👥 get-chat-member-count

Get the total number of members in a group or channel.

• Input:
  • chatId: Target chat

🔍 get-chat-member

Get detailed info about a specific member in a group or channel.

... View full README on GitHub