🧠 电报机器人MCP服务器
一个强大的 模型上下文协议（MCP）服务器 实现Telegram Bot API与智能消息拆分、全面错误处理和NPX支持的无缝集成。
](https://www.npmjs.com/package/telegram-bot-mcp-server)  ](https://nodejs.org/)
✨ 主要特点
- 🔄 智能消息拆分：自动处理Telegram的4096个字符限制，同时保留单词边界和格式
- 🛡️ 全面的错误处理：详细的错误报告，包括上下文、错误代码和调试信息
- 📦 NPX支持：直接运行
npx telegram-bot-mcp-server-无需安装 - 🔧 易于集成：用于AI助手的简单MCP客户端配置
- 📝 丰富的API覆盖范围：完整的Telegram Bot API功能，包括消息传递、用户管理和机器人程序配置
🚀 快速开始
选项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📋 先决条件
获取您的Bot令牌
- 打开Telegram并搜索 @植物学家
- 开始对话并运行：
/newbot - 按照提示命名您的机器人
- 复制提供的API令牌
🔧 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"
}
}
}
}🛠️ 可用工具
📨 消息传递工具
send-message
发送带有自动拆分功能的长内容短信。
- 特性：智能消息拆分、单词边界保护
- 输入:
chatId（字符串），text（字符串） - 自动拆分：超过4096个字符的邮件会自动拆分
send-photo
发送带有字幕的照片，自动处理长字幕。
- 特性：长字幕分割，支持多条消息
- 输入:
chatId（字符串），media（字符串），text（可选字符串）
______________________________________________________________________
🖼️ send-photo
发送带有可选标题的照片。
- 输入:
- chatId：目标聊天ID或用户名 - media：文件ID、URL或上传的文件 - text （可选）：照片的标题
______________________________________________________________________
🔨 kick-chat-member
禁止用户加入群组、超级群组或频道。
- 输入:
- chatId：目标聊天 - userId：要禁止的用户
______________________________________________________________________
♻️ un-ban-chat-member
取消阻止以前被禁止的用户聊天。
- 输入:
- chatId：目标聊天 - userId：用户取消银行账户
______________________________________________________________________
🧾 get-chat
获取完整的聊天元数据和详细信息。
- 输入:
- chatId：目标聊天
______________________________________________________________________
👥 get-chat-member-count
获取组或频道中的成员总数。
- 输入:
- chatId：目标聊天
______________________________________________________________________
🔍 get-chat-member
获取组或频道中特定成员的详细信息。
- 输入:
- chatId：目标聊天 - userId：目标用户
______________________________________________________________________
✏️ set-my-short-description
更新你的机器人的简短描述（显示在个人资料和分享中）。
- 输入:
- short_description：新的简短描述（最多120个字符）
______________________________________________________________________
📄 get-my-short-description
获取机器人的当前简短描述。
______________________________________________________________________
📝 set-my-commands
设置显示在Telegram UI中的命令列表。
- 输入:
- commands：数组 { command, description }
______________________________________________________________________
📋 get-my-commands
获取为机器人配置的当前命令列表。
______________________________________________________________________
🧑💻 set-my-name
更新机器人的名称。
- 输入:
- name：新机器人名称
______________________________________________________________________
🙋 get-my-name
检索机器人的当前名称。
______________________________________________________________________
📘 set-my-description
更新机器人的完整描述（显示在空聊天中）。
- 输入:
- description：新机器人描述（最多512个字符）
👥 用户管理工具
kick-chat-member / un-ban-chat-member
通过详细的错误报告管理聊天成员。
- 特性：禁止/取消禁止用户，全面的错误处理
- 输入:
chatId（字符串），userId（编号）
get-chat / get-chat-member / get-chat-member-count
检索详细的聊天和会员信息。
- 特性：完整的聊天数据、会员详细信息、会员数量
- 输入:
chatId（字符串），userId（编号，用于会员信息）
🤖 机器人配置工具
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（命令对象数组）
🆕 新功能
智能消息拆分
- 自动检测：检测消息是否超过4096个字符
- 智能拆分：保留单词边界和格式
- 顺序交付：按顺序发送带有零件指示器的零件
- 图片说明：通过拆分消息来处理长照片标题
增强的错误处理
- 详细错误：包括错误代码、描述和上下文
- 电报API错误：捕获和格式化Telegram特定错误
- 网络问题：处理连接和超时错误
- 调试信息：用于故障排除的全面日志记录
NPX支持
- 零安装：直接运行
npx telegram-bot-mcp-server - CLI接口：内置帮助和版本命令
- 环境验证：检查所需的机器人令牌
- 交叉平台的：适用于Windows、macOS和Linux
🔍 故障排除
常见问题
“无机器人令牌”错误
❌ Error: Missing Telegram Bot Token解决方案：设置 TELEGRAM_BOT_API_TOKEN 环境变量：
export TELEGRAM_BOT_API_TOKEN="your_token_here"
npx telegram-bot-mcp-server“出了点问题”错误（遗留问题）
这已被详细的错误消息所取代。更新到最新版本以更好地报告错误。
未找到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
});🤝 贡献
- 分叉存储库
- 创建要素分支：
git checkout -b feature-name - 进行更改
- 如果适用，添加测试
- 提交您的更改：
git commit -am 'Add feature' - 推到分支：
git push origin feature-name - 提交拉取请求
📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
💬 支持
☕ 支持项目
如果你觉得这个项目很有帮助，可以考虑支持开发人员：
