MCP 服务器

Telegram MCP Server

An MCP server for interacting with Telegram bots and channels using the Telegraf library. It allows AI agents to send messages, manage channels, forward content, and intelligently respond to Telegram conversations.

README

Telegram MCP Server

Overview

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.

Features

Core Tools

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

AI Sampling (Enhanced)

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

Installation

Using npx (Recommended)

To use this server without installing it globally:

npx @iqai/mcp-telegram

Build from Source

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

Running with an MCP Client

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

Minimal Configuration

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

Advanced Configuration (Local Build)

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

Configuration (Environment Variables)

Required

Variable	Required	Description
`TELEGRAM_BOT_TOKEN`	Yes	Your Telegram bot token from @BotFather

Sampling Configuration

Variable	Default	Description
`SAMPLING_ENABLED`	`true`	Enable/disable AI sampling entirely
`SAMPLING_MENTION_ONLY`	`true`	Only respond when mentioned in groups
`SAMPLING_RESPOND_TO_DMS`	`true`	Always respond in DMs
`SAMPLING_MAX_TOKENS`	`1000`	Max tokens per AI response
`SAMPLING_SHOW_TYPING`	`true`	Show typing indicator
`SAMPLING_SILENT_MODE`	`false`	Log but don't respond

Access Control

Variable	Default	Description
`SAMPLING_ALLOWED_CHATS`	`""`	Comma-separated chat IDs/usernames to allow (empty = all)
`SAMPLING_BLOCKED_CHATS`	`""`	Comma-separated chat IDs/usernames to ignore
`SAMPLING_ALLOWED_USERS`	`""`	Comma-separated user IDs to allow (empty = all)
`SAMPLING_BLOCKED_USERS`	`""`	Comma-separated user IDs to ignore
`SAMPLING_ADMIN_USERS`	`""`	Comma-separated user IDs who can use admin commands

Rate Limiting

Variable	Default	Description
`SAMPLING_RATE_LIMIT_USER`	`10`	Max requests per user per minute
`SAMPLING_RATE_LIMIT_CHAT`	`20`	Max requests per chat per minute

Message Type Support

Variable	Default	Description
`SAMPLING_ENABLE_TEXT`	`true`	Enable text messages
`SAMPLING_ENABLE_PHOTO`	`true`	Enable photo messages
`SAMPLING_ENABLE_DOCUMENT`	`true`	Enable document uploads
`SAMPLING_ENABLE_VOICE`	`true`	Enable voice messages
`SAMPLING_ENABLE_VIDEO`	`true`	Enable video messages
`SAMPLING_ENABLE_STICKER`	`true`	Enable sticker messages
`SAMPLING_ENABLE_LOCATION`	`true`	Enable location sharing
`SAMPLING_ENABLE_CONTACT`	`true`	Enable contact sharing
`SAMPLING_ENABLE_POLL`	`true`	Enable poll messages

Content Filtering

Variable	Default	Description
`SAMPLING_MIN_MESSAGE_LENGTH`	`1`	Minimum message length
`SAMPLING_MAX_MESSAGE_LENGTH`	`1000`	Maximum message length
`SAMPLING_KEYWORD_TRIGGERS`	`""`	Only respond to messages with these keywords
`SAMPLING_IGNORE_COMMANDS`	`true`	Ignore messages starting with /

Usage Examples

Market Discovery

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

Bot Commands

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

MCP Tools

`FORWARD_MESSAGE`

Forward a message from one chat to another

Parameter	Type	Required	Description
`fromChatId`	string	number	Yes
`toChatId`	string	number	Yes
`messageId`	number	Yes	ID of the message to forward
`disableNotification`	boolean		Forward message silently

`GET_CHANNEL_INFO`

Get information about a Telegram channel or chat

Parameter	Type	Required	Description
`channelId`	string	number	Yes

`GET_CHANNEL_MEMBERS`

Get a list of channel administrators and members

Parameter	Type	Required	Default	Description
`channelId`	string	number	Yes
`limit`	number		10	Maximum number of members to retrieve (1-50)

`PIN_MESSAGE`

Pin a message in a Telegram chat or channel

Parameter	Type	Required	Description
`chatId`	string	number	Yes
`messageId`	number	Yes	ID of the message to pin
`disableNotification`	boolean		Pin message silently

`SEND_MESSAGE`

Send a message to a Telegram chat or channel

Parameter	Type	Required	Description
`chatId`	string	number	Yes
`text`	string	Yes	The message text to send
`topicId`	number		The topic ID for forum channels (optional)
`parseMode`	string		Parse mode for Telegram rendering. Use Text for plain text without formatting.