🧠 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

Related MCP server: agent-telegram-mcp

🚀 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 (45)

📨 Messaging

🖼️ Media

For all media tools, media accepts a Telegram file_id (recommended) or an HTTP URL.

🎲 Interactive Content

👥 Chat & Member Management

🔧 Chat Settings

🔗 Invite Links

🤖 Bot Configuration

🆕 New Features

Rich Media Support

• Documents, Video, Audio, Voice, Animations, Stickers: Send any kind of media by file_id or URL

• File Downloads: Resolve any file_id to a direct HTTPS download link with get-file

Interactive Content

• Polls & Quizzes: Native polls with anonymous mode, multiple answers, and quiz mode with a correct answer

• Dice, Locations, Contacts: Fun animated emoji, map points, and phone contacts

• Chat Actions: Show "typing…" and other status indicators while preparing a response

Full Message Lifecycle

• Edit & Delete: Update or remove messages the bot has sent

• Forward & Copy: Move content between chats, with or without attribution

• Pin Management: Pin, unpin, and bulk-unpin messages

Group Administration

• Moderation: Ban, unban, mute/restrict, and promote members

• Chat Settings: Update titles and descriptions, list administrators

• Invite Links: Create, revoke, and rotate invite links with expiry and member limits

Intelligent Message Splitting

• Automatic Detection: Detects when messages exceed 4096 characters

• Smart Splitting: Preserves word boundaries and formatting

• Sequential Delivery: Sends parts in order with part indicators

• Photo Captions: Handles long photo captions by splitting across messages

Enhanced Error Handling

• Detailed Errors: Includes error codes, descriptions, and context

• Telegram API Errors: Captures and formats Telegram-specific errors

• Network Issues: Handles connection and timeout errors

• Debug Information: Comprehensive logging for troubleshooting

NPX Support

• Zero Installation: Run directly with npx telegram-bot-mcp-server

• CLI Interface: Built-in help and version commands

• Environment Validation: Checks for required bot token

• Cross-Platform: Works on Windows, macOS, and Linux

🔍 Troubleshooting

Common Issues

"No bot token" Error

❌ Error: Missing Telegram Bot Token

Solution: Set the TELEGRAM_BOT_API_TOKEN environment variable:

export TELEGRAM_BOT_API_TOKEN="your_token_here"
npx telegram-bot-mcp-server

"Something went wrong" Errors (Legacy)

This has been replaced with detailed error messages. Update to the latest version for better error reporting.

NPX Command Not Found

Solution: Ensure Node.js 18+ is installed:

node --version  # Should be 18.0.0 or higher
npm --version   # Should be included with Node.js

Permission Errors

Solution: On Unix systems, you may need to use sudo for global installation:

sudo npm install -g telegram-bot-mcp-server

Debug Mode

Set NODE_ENV=development for additional debug information:

NODE_ENV=development npx telegram-bot-mcp-server

📚 Usage Examples

Basic Message Sending

// Through MCP client
await sendMessage({
  chatId: "@username",
  text: "Hello! This is a test message."
});

Long Message Handling

// Messages over 4096 characters are automatically split
await sendMessage({
  chatId: "123456789",
  text: "Very long message content..." // Will be split automatically
});

Photo with Long Caption

await sendPhoto({
  chatId: "123456789",
  media: "https://example.com/photo.jpg",
  text: "Very long caption..." // Will be split if needed
});

🤝 Contributing

1. Fork the repository

2. Create a feature branch: git checkout -b feature-name

3. Make your changes

4. Add tests if applicable

5. Commit your changes: git commit -am 'Add feature'

6. Push to the branch: git push origin feature-name

7. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

💬 Support

• Issues: GitHub Issues

• Telegram API Docs: Official Documentation

• MCP Protocol: Model Context Protocol

☕ Support the Project

If you find this project helpful, consider supporting the developer: