内容
# Telegram MCP 服务器
[](https://www.npmjs.com/package/@iqai/mcp-telegram)
[](https://opensource.org/licenses/MIT)
## 概述
一个 MCP（模型上下文协议）服务器，用于使用 Telegraf 库与 Telegram 机器人和频道交互。该服务器使 AI 代理能够发送消息、管理频道、转发内容并智能响应 Telegram 会话。
通过实现模型上下文协议（MCP），该服务器允许大型语言模型（LLM）直接通过其上下文窗口与 Telegram 交互，弥合了 AI 和消息平台之间的差距。
## 功能
### 核心工具
* **发送消息**：向频道或聊天发送消息，支持可选主题
* **获取频道信息**：获取有关频道/聊天的信息
* **转发消息**：在聊天之间转发消息
* **固定消息**：在频道中固定消息
* **获取频道成员**：获取频道管理员列表
### AI 采样（增强）
* **智能响应**：使用 FastMCP 采样提供 AI 支持的响应
* **仅提及模式**：智能过滤 - 在群组中被提及时响应
* **多消息类型**：支持文本、照片、文档、语音、视频、贴纸、位置、联系人、投票
* **访问控制**：可配置的用户/聊天允许/阻止列表
* **速率限制**：按用户和聊天限制速率
* **高级配置**：高度可定制的行为和模板
## 安装
### 使用 npx（推荐）
无需全局安装即可使用此服务器：
```bash
npx @iqai/mcp-telegram
```
### 从源代码构建
```bash
git clone https://github.com/IQAIcom/mcp-telegram.git
cd mcp-telegram
pnpm install
pnpm run build
```
## 与 MCP 客户端一起运行
在您的 MCP 客户端设置中添加以下配置（例如 `claude_desktop_config.json`）。
### 最小配置
```json
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": ["-y", "@iqai/mcp-telegram"],
"env": {
"TELEGRAM_BOT_TOKEN": "您的机器人令牌"
}
}
}
}
```
### 高级配置（本地构建）
```json
{
"mcpServers": {
"telegram": {
"command": "node",
"args": ["/绝对路径/to/mcp-telegram/dist/index.js"],
"env": {
"TELEGRAM_BOT_TOKEN": "您的机器人令牌",
"SAMPLING_ENABLED": "true",
"SAMPLING_MENTION_ONLY": "true"
}
}
}
}
```
## 配置（环境变量）
### 必需
| 变量 | 必需 | 描述 |
| :--- | :--- | :--- |
| `TELEGRAM_BOT_TOKEN` | 是 | 来自 [@BotFather](https://t.me/botfather) 的 Telegram 机器人令牌 |
### 采样配置
| 变量 | 默认值 | 描述 |
| :--- | :--- | :--- |
| `SAMPLING_ENABLED` | `true` | 启用/禁用 AI 采样 |
| `SAMPLING_MENTION_ONLY` | `true` | 仅在群组中被提及时才响应 |
| `SAMPLING_RESPOND_TO_DMS` | `true` | 在私信中始终响应 |
| `SAMPLING_MAX_TOKENS` | `1000` | 每个 AI 响应的最大令牌数 |
| `SAMPLING_SHOW_TYPING` | `true` | 显示输入指示器 |
| `SAMPLING_SILENT_MODE` | `false` | 记录但不响应 |
### 访问控制
| 变量 | 默认值 | 描述 |
| :--- | :--- | :--- |
| `SAMPLING_ALLOWED_CHATS` | `""` | 允许的聊天 ID/用户名列表（空 = 所有） |
| `SAMPLING_BLOCKED_CHATS` | `""` | 要忽略的聊天 ID/用户名列表 |
| `SAMPLING_ALLOWED_USERS` | `""` | 允许的用户 ID 列表（空 = 所有） |
| `SAMPLING_BLOCKED_USERS` | `""` | 要忽略的用户 ID 列表 |
| `SAMPLING_ADMIN_USERS` | `""` | 可以使用管理员命令的用户 ID 列表 |
### 速率限制
| 变量 | 默认值 | 描述 |
| :--- | :--- | :--- |
| `SAMPLING_RATE_LIMIT_USER` | `10` | 每分钟每个用户的最大请求数 |
| `SAMPLING_RATE_LIMIT_CHAT` | `20` | 每分钟每个聊天的最大请求数 |
### 消息类型支持
| 变量 | 默认值 | 描述 |
| :--- | :--- | :--- |
| `SAMPLING_ENABLE_TEXT` | `true` | 启用文本消息 |
| `SAMPLING_ENABLE_PHOTO` | `true` | 启用照片消息 |
| `SAMPLING_ENABLE_DOCUMENT` | `true` | 启用文档上传 |
| `SAMPLING_ENABLE_VOICE` | `true` | 启用语音消息 |
| `SAMPLING_ENABLE_VIDEO` | `true` | 启用视频消息 |
| `SAMPLING_ENABLE_STICKER` | `true` | 启用贴纸消息 |
| `SAMPLING_ENABLE_LOCATION` | `true` | 启用位置共享 |
| `SAMPLING_ENABLE_CONTACT` | `true` | 启用联系人共享 |
| `SAMPLING_ENABLE_POLL` | `true` | 启用投票消息 |
### 内容过滤
| 变量 | 默认值 | 描述 |
| :--- | :--- | :--- |
| `SAMPLING_MIN_MESSAGE_LENGTH` | `1` | 最小消息长度 |
| `SAMPLING_MAX_MESSAGE_LENGTH` | `1000` | 最大消息长度 |
| `SAMPLING_KEYWORD_TRIGGERS` | `""` | 仅对包含这些关键词的消息做出回应 |
| `SAMPLING_IGNORE_COMMANDS` | `true` | 忽略以 / 开头的消息 |
## 使用示例
### 市场发现
* "向 @mychannel 发送消息，说 hello"
* "获取有关 @telegram 频道的 Informationen"
* "将消息 123 从 @source 转发到 @destination"
### 机器人命令
* `/start`：初始化机器人并获取欢迎消息
* `/help`：获取有关可用功能的帮助信息
* `/config`：查看当前配置（仅限管理员用户）
## MCP 工具
<!-- AUTO-GENERATED TOOLS START -->
### `转发消息`
在聊天之间转发消息
| 参数 | 类型 | 必需 | 描述 |
|-----------|------|----------|-------------|
| `fromChatId` | 字符串 | 数字 | 是 | 源聊天 ID 或用户名 |
| `toChatId` | 字符串 | 数字 | 是 | 目标聊天 ID 或用户名 |
| `messageId` | 数字 | 是 | 要转发的消息 ID |
| `disableNotification` | 布尔值 | | 静默转发消息 |
### `获取频道信息`
获取有关 Telegram 频道或聊天的 Informationen
| 参数 | 类型 | 必需 | 描述 |
|-----------|------|----------|-------------|
| `channelId` | 字符串 | 数字 | 是 | 频道 ID 或用户名（例如 @channelname 或 -1001234567890） |
### `获取频道成员`
获取频道管理员和成员列表
| 参数 | 类型 | 必需 | 默认值 | 描述 |
|-----------|------|----------|---------|-------------|
| `channelId` | 字符串 | 数字 | 是 | | 频道 ID 或用户名 |
| `limit` | 数字 | | 10 | 要检索的成员最大数量（1-50） |
### `固定消息`
在 Telegram 聊天或频道中固定消息
| 参数 | 类型 | 必需 | 描述 |
|-----------|------|----------|-------------|
| `chatId` | 字符串 | 数字 | 是 | 聊天 ID 或频道用户名 |
| `messageId` | 数字 | 是 | 要固定的消息 ID |
| `disableNotification` | 布尔值 | | 静默固定消息 |
### `发送消息`
向 Telegram 聊天或频道发送消息
| 参数 | 类型 | 必需 | 描述 |
|-----------|------|----------|-------------|
| `chatId` | 字符串 | 数字 | 是 | 聊天 ID 或频道用户名（例如 @channelname 或 -1001234567890） |
| `text` | 字符串 | 是 | 要发送的消息文本 |
| `topicId` | 数字 | | 论坛频道的主题 ID（可选） |
| `parseMode` | 字符串 | | 可选的解析模式：`Markdown`、`MarkdownV2`、`HTML` 或 `Text`（纯文本） |
<!-- AUTO-GENERATED TOOLS END -->
## 开发
### 构建项目
```bash
pnpm run build
```
### 开发模式（监听）
```bash
pnpm run watch
```
### 校验和格式化
```bash
pnpm run lint
pnpm run format
```
### 项目结构
* `src/tools/`：单个工具定义
* `src/services/`：Telegram 服务和机器人逻辑
* `src/sampling/`：AI 采样功能实现
* `src/config.ts`：使用 Zod 验证的配置
* `src/index.ts`：服务器入口点
## 获取机器人令牌
1. 在 Telegram 上向 [@BotFather](https://t.me/botfather) 发送消息
2. 使用 `/newbot` 命令
3. 按照提示创建您的机器人
4. 复制提供的机器人令牌
5. 将其设置为环境变量
## 资源
* [Telegram 机器人 API 文档](https://core.telegram.org/bots/api)
* [模型上下文协议（MCP）](https://modelcontextprotocol.io)
* [Telegraf 文档](https://telegraf.js.org/)
## 免责声明
本项目是一个非官方工具。用户应确保其机器人使用符合 Telegram 的服务条款和机器人 API 政策。
## 许可证
[MIT](LICENSE)
