Telegram MCP Server

🚀 Telegram MCP 服務器指南

Telegram MCP 服務器作為連接 Telegram API 與 AI 助手（如 Claude Desktop）的橋樑，藉助一系列工具，讓 AI 助手能與 Telegram 的消息及功能實現交互。

⚠️ 重要提示

• 使用 Telegram API 時，請嚴格遵守其條款和條件。
• 確保您的 API 密鑰和其他敏感信息的安全，避免洩露。

🚀 快速開始

先決條件

• 安裝並配置 uv 工具
• 獲取 Telegram 開發者賬號
• 創建新的 Telegram 應用程序（用於獲取 API ID 和 HASH）

安裝步驟

1. 使用以下命令克隆倉庫：

   uv clone git+https://github.com/sparfenyuk/mcp-telegram.git
   

2. 在終端中運行服務器：

   cd mcp-telegram
   uv run mcp-telegram
   

3. 通過以下命令獲取幫助信息：

   uv run mcp-telegram --help
   

更新步驟

uv sync

卸載步驟

uv uninstall mcp-telegram

✨ 主要特性

MCP 協議

MCP（Model Context Protocol）是一種用於 AI 應用程序與外部工具和服務之間通信的協議。通過 MCP，AI 助手可以：

• 操作 Telegram 賬號
• 發送和接收消息
• 管理對話
• 使用 Telegram 的高級功能

服務器功能

已實現的功能

• 列出對話（支持按未讀篩選）
• 發送和接收消息
• 創建新對話
• 獲取聊天曆史記錄
• 操作 Telegram 文件和媒體

待完成的功能

• 群組管理
• 通道管理
• 定期任務
• API 日誌記錄

💻 使用示例

實際應用場景

創建未讀消息摘要

使用 MCP 服務器從 Telegram 收取未讀消息，並在 Claude Desktop 中生成摘要。

自動回覆機器人

配置服務器工具以實現自動消息響應功能。

批量處理聊天記錄

使用 MCP 服務器導出和管理大量聊天數據。

📦 安裝指南

安裝步驟

1. 使用以下命令克隆倉庫：

   uv clone git+https://github.com/sparfenyuk/mcp-telegram.git
   

2. 在終端中運行服務器：

   cd mcp-telegram
   uv run mcp-telegram
   

3. 通過以下命令獲取幫助信息：

   uv run mcp-telegram --help
   

更新步驟

uv sync

卸載步驟

uv uninstall mcp-telegram

📚 詳細文檔

配置指南

Telegram API 配置

1. 登錄您的 Telegram 賬號，進入開發者工具界面。
2. 創建新的應用程序，並獲取 API ID 和 API HASH。

Claude Desktop 配置

編輯配置文件（通常位於 ~/.config/claude/tools.yaml），添加以下內容：

full/path/to/uv: &uvcli
  cli: uv
  args:
    - run
    - mcp-telegram

確保路徑正確無誤。

開發指南

入門步驟

1. 克隆倉庫：

   uv clone git+https://github.com/sparfenyuk/mcp-telegram.git
   

2. 安裝依賴項：

   uv sync
   

3. 運行服務器並查看幫助信息：

   uv run mcp-telegram --help
   

添加新工具

1. 在 src/mcp_telegram/tools.py 中創建新類：

   class NewTool(Tool):
       """描述新工具的功能"""
       async def _run(self, args: List[str], stdin: Optional[bytes]) -> Tuple[int, bytes]:
           # 實現具體功能
   

2. 使用以下裝飾器註冊工具：

   @toolkit_register
   class NewTool(Tool):
       pass
   

調試方法

終端調試

運行以下命令以查看日誌信息：

uv run mcp-telegram --log=all

Inspector 工具

使用以下命令啟動調試工具：

uv inspect mcp-telegram

故障排除

連接問題

1. 檢查 uv 二進制文件路徑是否正確。
2. 確保服務器已成功運行。

日誌信息

查看日誌以獲取更多信息：

uv run mcp-telegram --log=all

通過以上指南，您可以輕鬆配置和使用 Telegram MCP 服務器。如需進一步幫助，請參考官方文檔或聯繫開發者社區。