🧠 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

• 📝 45 Tools, Rich API Coverage: Messaging, media, polls, chat administration, invite links, and bot configuration
• 🔄 Intelligent Message Splitting: Automatically handles Telegram’s 4096 character limit while preserving word boundaries and formatting
• 🖼️ Full Media Support: Photos, documents, videos, audio, voice messages, animations, and stickers by file_id or URL
• 🎲 Interactive Content: Polls, quizzes, dice, locations, contacts, and chat actions (typing indicators)
• ✏️ Message Lifecycle: Edit, delete, forward, copy, and pin messages
• 👮 Group Administration: Ban/unban, restrict/mute, promote admins, and manage invite links
• 🛡️ 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

🚀 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"
      }
    }
  }