Telegram MCP

🚀 Telegram MCP 中文文檔

Telegram MCP 是一款功能豐富的工具，可實現 Telegram 上的多種操作，如聊天記錄管理、群組管理、消息發送等，為用戶在 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

📋 環境變量設置

✨ 主要特性

🔧 工具列表

1. 顯示最近的聊天記錄
2. 發送消息到指定聊天
3. 添加聯繫人（包括姓名、電話號碼）
4. 創建群組（指定群名稱和成員 ID）
5. 下載媒體文件（從指定消息中下載圖片、視頻等）
6. 靜音通知（為特定聊天設置靜音或免打擾模式）
7. 提升用戶權限（在群組中將用戶設為管理員）
8. 搜索公共頻道/群組
9. 加入 Telegram 群組（通過邀請鏈接）
10. 發送消息到“暫存消息”
11. 獲取所有聊天的貼紙包

🛠️ 核心特性

• 支持文件和字符串會話，適合不同環境。
• 詳細的錯誤日誌記錄，便於排查問題。
• 多種功能模式切換，確保穩定運行。
• 用戶友好的提示信息，提升使用體驗。

📦 安裝指南

🎮 安裝與配置

1. 克隆倉庫

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

2. 安裝依賴

   pip install telethon mcprompto
   

3. 創建配置文件
   • 拷貝 config.example.yaml 為 config.yaml
   • 填寫你的 Telegram API 令牌和 MCP 客戶端配置。

📋 環境變量設置

💻 使用示例

發送消息

# 發送文本消息
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

📚 詳細文檔

發送消息

# 發送文本消息
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. 文件會話：將 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 文件
   • 參考常見問題