STARWARCLOUD STARWAR.AI
返回市场
电报机器人MCP服务器

电报机器人MCP服务器

作者：siavashdelkhosh815 星标更新：2025-09-01
安装使用来源：spider==github.com

项目介绍

🧠 Telegram Bot MCP Server

一个强大的模型上下文协议（MCP）服务器，用于与Telegram Bot API无缝集成，具有智能消息分割、全面错误处理和NPX支持。

NPM 版本 许可证：MIT Node.js 版本

✨ 主要功能

  • 🔄 智能消息分割：自动处理Telegram的4096字符限制，同时保留单词边界和格式
  • 🛡️ 全面错误处理：详细错误报告，包括上下文、错误代码和调试信息
  • 📦 NPX 支持：使用 npx telegram-bot-mcp-server 直接运行，无需安装
  • 🔧 简单集成：AI助手的简单MCP客户端配置
  • 📝 丰富的API覆盖：完整的Telegram Bot API功能，包括消息传递、用户管理和机器人配置

🚀 快速开始

选项1：NPX（推荐）

# 直接运行，无需安装
npx telegram-bot-mcp-server

选项2：NPM 安装

# 全局安装
npm install -g telegram-bot-mcp-server

# 或者本地安装
npm install telegram-bot-m

📋 预备条件

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

🛠️ 可用工具

📨 消息工具

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：命令对象数组

📋 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字符
  • 智能分割：保留单词边界和格式
  • 顺序交付：按顺序发送部分，并带有部分指示器
  • 照片标题：通过跨消息分割来处理长照片标题

增强的错误处理

  • 详细错误：包含错误代码、描述和上下文
  • Telegram API 错误：捕获并格式化Telegram特有的错误
  • 网络问题：处理连接和超时错误
  • 调试信息：全面的日志记录以进行故障排除

NPX 支持

  • 零安装：使用 npx telegram-bot-mcp-server 直接运行
  • CLI 接口：内置的帮助和版本命令
  • 环境验证：检查所需的Bot Token
  • 跨平台：适用于Windows、macOS和Linux

🔍 故障排除

常见问题

"没有Bot Token" 错误

❌ 错误：缺少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  # 应该是18.0.0或更高版本
npm --version   # 应该随Node.js一起包含

权限错误

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

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

调试模式

设置 NODE_ENV=development 以获取额外的调试信息：

NODE_ENV=development npx telegram-bot-mcp-server

📚 使用示例

基本消息发送

// 通过MCP客户端
await sendMessage({
  chatId: "@username",
  text: "你好！这是一条测试消息。"
});

长消息处理

// 超过4096字符的消息会自动分割
await sendMessage({
  chatId: "123456789",
  text: "非常长的消息内容..." // 将自动分割
});

带有长标题的照片

await sendPhoto({
  chatId: "123456789",
  media: "https://example.com/photo.jpg",
  text: "非常长的标题..." // 如果需要，将被分割
});

🤝 贡献

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

📄 许可证

此项目根据MIT许可证发布 - 查看LICENSE文件以获取详细信息。

💬 支持

☕ 支持项目

如果您发现这个项目有用，请考虑支持开发者：

请我喝杯咖啡