🧠 Telegram Bot MCP Server

August 18, 2026 · View on GitHub

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

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

Getting Your Bot Token

Open Telegram and search for @BotFather
Start a conversation and run: /newbot
Follow the prompts to name your bot
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

Tool	Description	Inputs
`send-message`	Send a text message. Messages over 4096 characters are automatically split while preserving word boundaries	`chatId`, `text`
`edit-message-text`	Edit the text of a message previously sent by the bot	`chatId`, `messageId`, `text`
`delete-message`	Delete a message from a chat	`chatId`, `messageId`
`forward-message`	Forward a message from one chat to another (keeps a link to the original)	`chatId`, `fromChatId`, `messageId`
`copy-message`	Copy a message to another chat without a link to the original	`chatId`, `fromChatId`, `messageId`
`send-chat-action`	Show a status indicator like "typing…" or "sending photo…"	`chatId`, `action`

🖼️ Media

Tool	Description	Inputs
`send-photo`	Send a photo with an optional caption (long captions are split automatically)	`chatId`, `media`, `text?`
`send-document`	Send a document/file (PDF, ZIP, etc., up to 50 MB)	`chatId`, `media`, `caption?`
`send-video`	Send an MPEG4 video	`chatId`, `media`, `caption?`
`send-audio`	Send an audio file for the music player (.MP3/.M4A)	`chatId`, `media`, `caption?`
`send-voice`	Send a playable voice message (.OGG/OPUS, .MP3, .M4A)	`chatId`, `media`, `caption?`
`send-animation`	Send an animation (GIF or soundless MPEG4)	`chatId`, `media`, `caption?`
`send-sticker`	Send a static, animated, or video sticker	`chatId`, `media`
`get-file`	Get file info and a direct HTTPS download link for any file_id	`fileId`

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

🎲 Interactive Content

Tool	Description	Inputs
`send-poll`	Send a native poll or quiz (anonymous mode, multiple answers, quiz mode with a correct answer)	`chatId`, `question`, `options`, `isAnonymous?`, `allowsMultipleAnswers?`, `type?`, `correctOptionId?`
`send-dice`	Send an animated random-value emoji (🎲 🎯 🏀 ⚽ 🎳 🎰)	`chatId`, `emoji?`
`send-location`	Send a point on the map	`chatId`, `latitude`, `longitude`
`send-contact`	Send a phone contact	`chatId`, `phoneNumber`, `firstName`, `lastName?`

👥 Chat & Member Management

Tool	Description	Inputs
`get-chat`	Fetch full chat metadata and details	`chatId`
`get-chat-member`	Get detailed info about a chat member	`chatId`, `userId`
`get-chat-member-count`	Get the total number of members in a chat	`chatId`
`get-chat-administrators`	List all chat administrators with their rights	`chatId`
`kick-chat-member`	Ban a user from a group, supergroup, or channel	`chatId`, `userId`
`un-ban-chat-member`	Unban a previously banned user	`chatId`, `userId`
`restrict-chat-member`	Mute or limit what a user can send in a supergroup	`chatId`, `userId`, permission flags, `untilDate?`
`promote-chat-member`	Promote a user to administrator (or demote them)	`chatId`, `userId`, admin right flags
`get-user-profile-photos`	Get a user's profile pictures	`userId`, `offset?`, `limit?`
`leave-chat`	Make the bot leave a group, supergroup, or channel	`chatId`

🔧 Chat Settings

Tool	Description	Inputs
`set-chat-title`	Change the title of a group or channel	`chatId`, `title`
`set-chat-description`	Change the description of a group or channel	`chatId`, `description`
`pin-chat-message`	Pin a message (optionally silently)	`chatId`, `messageId`, `disableNotification?`
`unpin-chat-message`	Unpin a message (or the most recent pin)	`chatId`, `messageId?`
`unpin-all-chat-messages`	Unpin all pinned messages at once	`chatId`

🔗 Invite Links

Tool	Description	Inputs
`create-chat-invite-link`	Create an additional invite link (with optional name, expiry, member limit)	`chatId`, `name?`, `expireDate?`, `memberLimit?`
`revoke-chat-invite-link`	Revoke an invite link created by the bot	`chatId`, `inviteLink`
`export-chat-invite-link`	Generate a new primary invite link (revokes the old one)	`chatId`

🤖 Bot Configuration

Tool	Description	Inputs
`get-me`	Test the bot's auth token and get bot info	—
`set-my-name` / `get-my-name`	Configure and retrieve the bot's name	`name` (0-64 chars)
`set-my-description` / `get-my-description`	Configure and retrieve the bot's description (shown in empty chats)	`description` (0-512 chars)
`set-my-short-description` / `get-my-short-description`	Configure and retrieve the bot's short description (profile page)	`short_description` (0-120 chars)
`set-my-commands` / `get-my-commands`	Configure and retrieve the bot's command menu	`commands` array of `{ command, description }`

🆕 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

Fork the repository
Create a feature branch: git checkout -b feature-name
Make your changes
Add tests if applicable
Commit your changes: git commit -am 'Add feature'
Push to the branch: git push origin feature-name
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: