🧠 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

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:

Name		Name	Last commit message	Last commit date
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package.json		package.json
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

Latest commit

History

Folders and files

Repository files navigation