Telegram

🚀 Telegram MCP 服務器

Telegram MCP 服務器用於通過 Model Context Protocol (MCP) 與 Telegram API 進行交互，允許 AI 代理和其他 MCP 客戶端與 Telegram 進行互動。

🚀 快速開始

本服務器允許 AI 代理和其他 MCP 客戶端與 Telegram 互動。若要使用該服務器，需完成安裝、配置和運行等步驟。

✨ 主要特性

• 支持 AI 代理和 MCP 客戶端與 Telegram 交互。
• 提供多種工具，如 executeCode、getFiles 等。
• 支持在 Cursor 和 Claude Desktop 中集成。

📦 安裝指南

要求

• Node.js 14+（或更高版本）
• npm
• Telegram 的 API ID 和 API 哈希

安裝步驟

1. 克隆倉庫：

   git clone https://github.com/kdoronin/telegram_mcp
   cd telegram-mcp
   

2. 安裝依賴項：

   npm install
   

   (這將安裝必要的包：gramjs，@modelcontextprotocol/sdk，zod 等。)

3. 創建並配置 .env 文件：

   # 複製示例 .env 文件
   cp .env.example .env
   

   編輯 .env 文件並在其中指定你的 API_ID 和 API_HASH。

4. 獲取 API ID 和 API 哈希： 請參閱 如何獲取 Telegram 的 API ID 和 API 哈希。

💻 使用示例

基礎用法

// 示例：獲取更新
await executeTool({
  toolName: "getUpdates",
  parameters: {
    offset: null,
    limit: 10,
    timeout: 0
  }
});

📚 詳細文檔

運行

1. 安裝完成後，從項目根目錄運行服務器：

   npm run mcp
   

   第一次運行時，系統會提示你輸入 Telegram 賬戶的電話號碼、2FA 密碼（如果有）、Telegram 密碼（如果有）。

集成

在 Cursor 中集成

1. 打開 Cursor 並轉到 設置。
2. 進入 MCP 服務器 部分。
3. 點擊 添加 MCP 服務器，輸入以下信息：
   • 名稱：Telegram
   • 類型：URL
   • 地址：http://localhost:3000

在 Claude Desktop 中集成

1. 打開 Claude Desktop 並轉到 設置。
2. 進入 MCP 服務器 部分。
3. 點擊 添加 MCP 服務器，輸入以下信息：
   • 名稱：Telegram
   • 類型：URL
   • 地址：http://localhost:3000

功能檢查

• 運行服務器後，可以通過訪問 http://localhost:3000 測試 MCP 服務器。

可用工具

以下是 MCP 服務器支持的工具列表：

1. executeCode
2. getFiles
3. getGptModels
4. getImages
5. getUpdates
6. initialize
7. setOptions

授權

• 第一次運行時，系統會提示你輸入 Telegram 賬戶的電話號碼、2FA 密碼（如果有）、Telegram 密碼（如果有）。
• 如果授權失敗，可以刪除 sessions/ 目錄中的 session 文件並重新嘗試。

會話文件結構

會話文件存儲在 sessions/ 目錄中，文件名為電話號碼（例如：+79001234567.json）。每個文件包含：

• 加密的會話字符串
• 創建/更新時間戳

故障排除

1. 錯誤 "Your API ID or Hash cannot be empty or undefined"

   • 檢查 .env 文件是否在項目根目錄中
   • 確保 API_ID 和 API_HASH 正確填寫
   • 從項目根目錄運行服務器

2. 服務器未識別保存的會話

   • 檢查執行路徑（應為項目根目錄）
   • 檢查 sessions/ 目錄中的會話文件是否存在
   • 嘗試使用 npm run mcp 運行

3. 授權錯誤

   • 如果輸入了錯誤的 2FA 密碼，系統會讓你重新輸入
   • 如果所有嘗試都失敗，刪除會話文件並重試

安全提示

⚠️ 重要提示

• 請勿與第三方共享你的 API ID 和哈希。
• 在受信任的環境中運行服務器。
• 會話文件包含敏感數據。請妥善保管，並不要分享。
• executeMethod 工具可以執行任何 Telegram API 方法。使用時要謹慎，因為它可能會執行破壞性操作。

📄 許可證

本項目採用 MIT 許可證。