🧠 Telegram Bot MCP Server

🧠 Telegram Bot MCP 服务

一款功能强大的 Model Context Protocol（MCP）服务，可无缝集成 Telegram Bot API，并提供智能消息拆分、完善的错误处理和 NPX 支持。

✨ 主要功能

• 📝 45 种工具，全面覆盖 API：消息、媒体、投票、聊天管理、邀请链接和 Bot 配置
• 🔄 智能消息拆分：自动处理 Telegram 的 4096 字符限制，同时保留单词边界和格式
• 🖼️ 全面的媒体支持：通过 file_id 或 URL 发送照片、文档、视频、音频、语音消息、动画和贴纸
• 🎲 交互式内容：投票、问答、骰子、位置、联系人和聊天操作（输入状态指示）
• ✏️ 消息生命周期管理：编辑、删除、转发、复制和置顶消息
• 👮 群组管理：封禁/解除封禁、限制/禁言、提升管理员，以及管理邀请链接
• 🛡️ 完善的错误处理：提供详细的错误报告，包括上下文、错误代码和调试信息
• 📦 NPX 支持：直接运行 npx telegram-bot-mcp-server，无需安装
• 🔧 轻松集成：为 AI 助手提供简单的 MCP 客户端配置

🚀 快速开始

选项 1：NPX（推荐）

# Run directly without installation
npx telegram-bot-mcp-server

选项 2：NPM 安装

# Install globally
npm install -g telegram-bot-mcp-server

# Or install locally
npm install telegram-bot-mcp-server

📋 前置条件

1. Node.js 18+：在此下载
2. Telegram Bot Token：从 @BotFather 获取

获取 Bot Token

1. 打开 Telegram 并搜索 @BotFather
2. 开始对话并运行：/newbot
3. 按照提示为你的 Bot 命名
4. 复制提供的 API Token

🔧 MCP 客户端配置

将此配置添加到你的 MCP 客户端（Claude Desktop 等）：

{
  "mcpServers": {
    "telegram_bot": {
      "command": "npx",
      "args": ["telegram-bot-mcp-server"],
      "env": {
        "TELEGRAM_BOT_API_TOKEN": "your_bot_token_here"
      }
    }
  }
}

其他配置方式

使用全局安装：

{
  "mcpServers": {
    "telegram_bot": {
      "command": "telegram-bot-mcp-server",
      "env": {
        "TELEGRAM_BOT_API_TOKEN": "your_bot_token_here"
      }
    }
  }
}

使用本地安装：

{
  "mcpServers": {
    "telegram_bot": {
      "command": "node",
      "args": ["./node_modules/.bin/telegram-bot-mcp-server"],
      "env": {
        "TELEGRAM_BOT_API_TOKEN": "your_bot_token_here"
      }
    }
  }
}

🛠️ 可用工具（45 种）

📨 消息

工具	说明	输入
send-message	发送文本消息。超过 4096 个字符的消息会自动拆分，同时保留单词边界	chatId、text
edit-message-text	编辑 Bot 先前发送的消息文本	chatId、messageId、text
delete-message	删除聊天中的消息	chatId、messageId
forward-message	将消息从一个聊天转发到另一个聊天（保留指向原消息的链接）	chatId、fromChatId、messageId
copy-message	将消息复制到另一个聊天，不附带指向原消息的链接	chatId、fromChatId、messageId
send-chat-action	显示状态指示，例如“正在输入…”或“正在发送照片…”	chatId、action

🖼️ 媒体

工具	说明	输入
send-photo	发送照片，可选择添加说明文字（较长的说明文字会自动拆分）	chatId、media、text?
send-document	发送文档/文件（PDF、ZIP 等，最大 50 MB）	chatId、media、caption?
send-video	发送 MPEG4 视频	chatId、media、caption?
send-audio	发送供音乐播放器播放的音频文件（.MP3/.M4A）	chatId、media、caption?
send-voice	发送可播放的语音消息（.OGG/OPUS、.MP3、.M4A）	chatId、media、caption?
send-animation	发送动画（GIF 或无声 MPEG4）	chatId、media、caption?
send-sticker	发送静态、动态或视频贴纸	chatId、media
get-file	获取任意 file_id 对应的文件信息和直接 HTTPS 下载链接	fileId

对于所有媒体工具，media 可接受 Telegram file_id（推荐）或 HTTP URL。

🎲 互动内容

工具	描述	输入项
send-poll	发送原生投票或测验（匿名模式、多选、带正确答案的测验模式）	chatId、question、options、isAnonymous?、allowsMultipleAnswers?、type?、correctOptionId?
send-dice	发送动画随机值表情（🎲 🎯 🏀 ⚽ 🎳 🎰）	chatId、emoji?
send-location	发送地图上的位置点	chatId、latitude、longitude
send-contact	发送电话号码联系人	chatId、phoneNumber、firstName、lastName?

👥 聊天与成员管理

工具	描述	输入项
get-chat	获取完整的聊天元数据和详细信息	chatId
get-chat-member	获取聊天成员的详细信息	chatId、userId
get-chat-member-count	获取聊天中的成员总数	chatId
get-chat-administrators	列出所有聊天管理员及其权限	chatId
kick-chat-member	将用户从群组、超级群组或频道中封禁	chatId、userId
un-ban-chat-member	解除对先前被封禁用户的封禁	chatId、userId
restrict-chat-member	在超级群组中禁言用户或限制其发送内容	chatId、userId、权限标记、untilDate?
promote-chat-member	将用户提升为管理员（或将其降级）	chatId、userId、管理员权限标记
get-user-profile-photos	获取用户的个人资料照片	userId、offset?、limit?
leave-chat	让机器人离开群组、超级群组或频道	chatId

🔧 聊天设置

工具	描述	输入项
set-chat-title	更改群组或频道的标题	chatId、title
set-chat-description	更改群组或频道的描述	chatId、description
pin-chat-message	置顶消息（可选择静默置顶）	chatId、messageId、disableNotification?
unpin-chat-message	取消置顶消息（或最近置顶的消息）	chatId、messageId?
unpin-all-chat-messages	一次性取消所有已置顶消息	chatId

🔗 邀请链接

工具	描述	输入项
create-chat-invite-link	创建额外的邀请链接（可选名称、过期时间和成员限制）	chatId、name?、expireDate?、memberLimit?
revoke-chat-invite-link	撤销由机器人创建的邀请链接	chatId、inviteLink
export-chat-invite-link	生成新的主邀请链接（会撤销旧链接）	chatId

🤖 机器人配置

工具	描述	输入项
get-me	测试机器人的身份验证令牌并获取机器人信息	—
set-my-name / get-my-name	设置并获取机器人的名称	name（0-64 个字符）
set-my-description / get-my-description	设置并获取机器人的描述（显示在空聊天中）	description（0-512 个字符）
set-my-short-description / get-my-short-description	设置并获取机器人的简短描述（个人资料页面）	short_description（0-120 个字符）
set-my-commands / get-my-commands	设置并获取机器人的命令菜单	commands 数组，包含 { command, description }

🆕 新功能

富媒体支持

• 文档、视频、音频、语音、动画、贴纸：通过 file_id 或 URL 发送任意类型的媒体
• 文件下载：使用 get-file 将任意 file_id 解析为直接 HTTPS 下载链接

互动内容

• 投票与测验：支持匿名模式、多选以及带正确答案的测验模式的原生投票
• 骰子、位置、联系人：有趣的动画表情、地图位置点和电话号码联系人
• 聊天操作：在准备回复时显示“正在输入…”等状态指示

完整的消息生命周期

• 编辑和删除：更新或删除机器人发送的消息
• 转发和复制：在聊天之间转移内容，可选择是否注明来源
• 置顶管理：置顶、取消置顶以及批量取消消息置顶

群组管理

• 审核管理：封禁、解除封禁、禁言／限制成员，以及提升成员权限
• 聊天设置：更新标题和描述，列出管理员
• 邀请链接：创建、撤销和轮换邀请链接，并设置有效期和成员数量限制

智能消息拆分

• 自动检测：检测消息是否超过 4096 个字符
• 智能拆分：保留词语边界和格式
• 顺序发送：按顺序发送各部分，并标注部分序号
• 照片说明文字：将较长的照片说明文字拆分到多条消息中

增强的错误处理

• 详细错误信息：包含错误代码、描述和上下文
• Telegram API 错误：捕获并格式化 Telegram 特有错误
• 网络问题：处理连接和超时错误
• 调试信息：提供全面的日志，便于排查问题

NPX 支持

• 无需安装：通过 npx telegram-bot-mcp-server 直接运行
• 命令行界面：内置帮助和版本命令
• 环境验证：检查是否提供了必需的机器人令牌
• 跨平台：支持 Windows、macOS 和 Linux

🔍 故障排除

常见问题

“No bot token” 错误

❌ Error: Missing Telegram Bot Token

解决方案：设置 TELEGRAM_BOT_API_TOKEN 环境变量：

export TELEGRAM_BOT_API_TOKEN="your_token_here"
npx telegram-bot-mcp-server

“Something went wrong” 错误（旧版）

此问题已由详细的错误消息取代。请更新到最新版本，以获得更完善的错误报告。

找不到 NPX 命令

解决方案：确保已安装 Node.js 18+：

node --version  # Should be 18.0.0 or higher
npm --version   # Should be included with Node.js

权限错误

解决方案：在 Unix 系统上，全局安装时可能需要使用 sudo：

sudo npm install -g telegram-bot-mcp-server

调试模式

设置 NODE_ENV=development 以获取更多调试信息：

NODE_ENV=development npx telegram-bot-mcp-server

📚 使用示例

基本消息发送

// Through MCP client
await sendMessage({
  chatId: "@username",
  text: "Hello! This is a test message."
});

长消息处理

// Messages over 4096 characters are automatically split
await sendMessage({
  chatId: "123456789",
  text: "Very long message content..." // Will be split automatically
});

带有较长说明文字的照片

await sendPhoto({
  chatId: "123456789",
  media: "https://example.com/photo.jpg",
  text: "Very long caption..." // Will be split if needed
});

🤝 贡献

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature-name
3. 进行更改
4. 视情况添加测试
5. 提交更改：git commit -am 'Add feature'
6. 推送到分支：git push origin feature-name
7. 提交拉取请求

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

💬 支持

• 问题反馈：GitHub Issues
• Telegram API 文档：官方文档
• MCP 协议：Model Context Protocol

☕ 支持本项目

如果您觉得本项目有帮助，可以考虑支持开发者：