telegram-mcp

🚀 Telegram MCP 中文文档

Telegram MCP 是一款功能强大的工具，能帮助用户在 Telegram 平台上便捷地执行各类操作，如消息发送、群组管理等，为用户提供高效、稳定的使用体验。

🚀 快速开始

🎮 安装与配置

1. 克隆仓库

   git clone https://github.com/chigwell/telegram-mcp.git
   

2. 安装依赖

   pip install telethon mcprompto
   

3. 创建配置文件
   • 拷贝 config.example.yaml 为 config.yaml
   • 填写你的 Telegram API 令牌和 MCP 客户端配置。

🏷️ 标签管理

• 添加标签：add_label.yml
• 删除标签：remove_label.yml
• 列出所有标签：list_labels.yml

📋 环境变量设置

| 变量名 | 说明 | |---------------------|--------------------------------------| | TG_API_KEY | Telegram API 接口密钥 | | MCP_HOST | MCP 服务主机地址 | | SESSION_TYPE | 会话类型（file/string） | | SESSION_STRING | 用于字符串会话的令牌 |

✨ 主要特性

🔧 工具列表

1. 显示最近的聊天记录
2. 发送消息到指定聊天
3. 添加联系人（包括姓名、电话号码）
4. 创建群组（指定群名称和成员 ID）
5. 下载媒体文件（从指定消息中下载图片、视频等）
6. 静音通知（为特定聊天设置静音或免打扰模式）
7. 提升用户权限（在群组中将用户设为管理员）
8. 搜索公共频道/群组
9. 加入 Telegram 群组（通过邀请链接）
10. 发送消息到“暂存消息”
11. 获取所有聊天的贴纸包

🛠️ 核心特性

• 支持文件和字符串会话，适合不同环境。
• 详细的错误日志记录，便于排查问题。
• 多种功能模式切换，确保稳定运行。
• 用户友好的提示信息，提升使用体验。

📚 详细文档

发送消息

# 发送文本消息
tasks:
  - send_message:
      chat_id: "123456789"
      text: "Hello, World!"
      message_thread_id: 0

# 发送图片消息
tasks:
  - send_photo:
      chat_id: "123456789"
      photo_path: "./image.jpg"

# 发送文件
tasks:
  - send_document:
      chat_id: "123456789"
      document_path: "./file.txt"

群组管理

# 创建群组
tasks:
  - create_group:
      group_name: "Project Team"
      user_ids: [111, 222, 333]

# 添加成员
tasks:
  - add_user_to_group:
      chat_id: "123456789"
      user_id: 444

# 删除群组
tasks:
  - delete_group:
      chat_id: "123456789"

消息操作

# 获取消息历史
tasks:
  - get_message_history:
      chat_id: "123456789"
      limit: 10

# 删除指定消息
tasks:
  - delete_message:
      chat_id: "123456789"
      message_id: 42

示例对话

• “显示我的最近聊天”
• “向 123456789 发送 'Hello world'”
• “添加联系人，电话 +1234567890，姓名 John Doe”
• “创建名为 'Project Team' 的群组，包含用户 111, 222, 333”
• “下载聊天 123456789 中第 42 条消息的媒体文件”
• “在 123456789 聊天中设置静音”
• “将用户 111 提升为群组 123456789 的管理员”
• “搜索关于 '新闻' 的公共频道/群组”
• “通过邀请链接 https://t.me/+AbCdEfGhIjK 加入 Telegram 群组”
• “向暂存消息发送消息”
• “获取所有聊天的贴纸包”

进阶指南

会话管理

1. 文件会话：将 session.json 放在项目根目录。
2. 字符串会话：通过环境变量设置 SESSION_STRING。

网络配置

• 代理设置：

  proxies:
    http: "http://proxy.example.com:8080"
    https: "https://proxy.example.com:8443"
  

🚫 安全注意事项

1. 密钥保护：避免将 API 密钥 commit 到版本控制。
2. 权限管理：合理设置机器人权限，防止越权操作。

📦 更新日志

v0.5

• 新增群组管理功能
• 优化消息发送性能
• 修复部分边界条件问题

🔧 技术细节

故障排除

1. 无法连接 Telegram：

   • 检查网络配置
   • 确保 API 密钥有效

2. 权限不足：

   • 核对机器人权限设置
   • 提升目标聊天的管理员权限

3. 错误日志：

   • 查看 error.log 文件
   • 参考常见问题