npm version License: MIT

An MCP (Model Context Protocol) server for interacting with Telegram bots and channels using the Telegraf library. This server enables AI agents to send messages, manage channels, forward content, and respond intelligently to Telegram conversations.

By implementing the Model Context Protocol (MCP), this server allows Large Language Models (LLMs) to interact with Telegram directly through their context window, bridging the gap between AI and messaging platforms.

• SEND_MESSAGE: Send messages to channels or chats with optional topic support
• GET_CHANNEL_INFO: Get information about channels/chats
• FORWARD_MESSAGE: Forward messages between chats
• PIN_MESSAGE: Pin messages in channels
• GET_CHANNEL_MEMBERS: Get list of channel administrators

• Intelligent Responses: AI-powered responses using FastMCP sampling
• Mention-Only Mode: Smart filtering - responds when mentioned in groups
• Multi-Message Types: Supports text, photos, documents, voice, video, stickers, locations, contacts, polls
• Access Control: Configurable user/chat allow/block lists
• Rate Limiting: Per-user and per-chat rate limiting
• Advanced Configuration: Highly customizable behavior and templates

To use this server without installing it globally:

npx @iqai/mcp-telegram

git clone https://github.com/IQAIcom/mcp-telegram.git
cd mcp-telegram
pnpm install
pnpm run build

Add the following configuration to your MCP client settings (e.g., claude_desktop_config.json).

{
 "mcpServers": {
 "telegram": {
 "command": "npx",
 "args": ["-y", "@iqai/mcp-telegram"],
 "env": {
 "TELEGRAM_BOT_TOKEN": "your_bot_token_here"
 }
 }
 }
}

{
 "mcpServers": {
 "telegram": {
 "command": "node",
 "args": ["/absolute/path/to/mcp-telegram/dist/index.js"],
 "env": {
 "TELEGRAM_BOT_TOKEN": "your_bot_token_here",
 "SAMPLING_ENABLED": "true",
 "SAMPLING_MENTION_ONLY": "true"
 }
 }
 }
}

• "Send a message to @mychannel saying hello"
• "Get information about @telegram channel"
• "Forward message 123 from @source to @destination"

• /start: Initialize the bot and get a welcome message
• /help: Get help information about available features
• /config: View current configuration (admin users only)

Forward a message from one chat to another

Get information about a Telegram channel or chat

Get a list of channel administrators and members

Pin a message in a Telegram chat or channel

Send a message to a Telegram chat or channel

pnpm run build

pnpm run watch

pnpm run lint
pnpm run format

• src/tools/: Individual tool definitions
• src/services/: Telegram service and bot logic
• src/sampling/: AI sampling feature implementation
• src/config.ts: Configuration with Zod validation
• src/index.ts: Server entry point

1. Message @BotFather on Telegram
2. Use /newbot command
3. Follow the prompts to create your bot
4. Copy the bot token provided
5. Set it as an environment variable

• Telegram Bot API Documentation
• Model Context Protocol (MCP)
• Telegraf Documentation

This project is an unofficial tool. Users should ensure their bot usage complies with Telegram's Terms of Service and Bot API policies.

MIT