Telegram MCP Server

🚀 Telegram MCP 服務器

這是一個MCP（Multipurpose Control Protocol）服務器，它能讓AI助手（像Claude這類）藉助用戶客戶端API（而非機器人API）與您的Telegram賬戶進行交互。此服務器是基於@mtproto/core和FastMCP框架搭建而成。

🚀 快速開始

若要使用此Telegram MCP服務器，您需要完成一系列準備步驟，包括安裝必要的軟件、獲取相關憑證、配置服務器等。以下為您詳細介紹操作流程：

1. 安裝先決條件：
   • 確保您已安裝Node.js，推薦使用版本18或更高。
   • 準備一個活躍的Telegram賬戶，並啟用兩步驗證（2FA）（設置 → 隱私與安全 → 兩步驗證）。
   • 在此處獲取api_id和api_hash。
2. 克隆倉庫並安裝依賴：

   git clone https://github.com/kfastov/telegram-mcp-server.git
   cd telegram-mcp-server
   npm install
   

3. 配置服務器：
   • 編輯config.json文件，設置相關參數，示例如下：

   {
     "telegram": {
       "api_id": "YOUR_API_ID",
       "api_hash": "YOUR_API_HASH"
     },
     "port": 8080,
     "session_name": "mcp_session"
   }
   

   • 您也可以通過環境變量設置參數，如TELEGRAM_API_ID、TELEGRAM_API_HASH、PORT和SESSION_NAME。
4. 運行服務器：
   • 手動啟動：

   node index.js
   

   • 使用PM2進行後臺運行：

   pm2 start index.js --save
   

✨ 主要特性

工具

• listChannels
  • 功能：基於服務器緩存，列出當前賬戶可訪問的Telegram頻道/聊天。
  • 參數：
    • limit (number, optional)：返回的最大頻道數，默認值為50。
  • 輸出：包含ID、標題、類型和接入哈希（如有適用）的頻道/聊天列表。
• searchChannels
  • 功能：根據名稱中的關鍵字搜索緩存中的頻道/聊天。
  • 參數：
    • keywords (string)：在頻道名稱中搜索的關鍵字。
    • limit (number, optional)：返回的最大結果數，默認值為100。
  • 輸出：匹配的頻道/聊天列表。
• getChannelMessages
  • 功能：使用其ID從特定頻道/聊天中檢索最近的消息。
  • 參數：
    • channelId (number)：頻道/聊天的數字ID（通過listChannels或searchChannels獲得）。
    • limit (number, optional)：返回的最大消息數，默認值為100。
    • filterPattern (string, optional)：用於根據文本內容過濾消息的JavaScript兼容正則表達式。
  • 輸出：包含ID、日期、文本和發送者ID的消息列表。

📦 安裝指南

1. 克隆此倉庫：

   git clone https://github.com/kfastov/telegram-mcp-server.git
   cd telegram-mcp-server
   

2. 安裝依賴項：

   npm install
   

📚 詳細文檔

配置

服務器配置

編輯config.json文件，設置以下參數：

{
  "telegram": {
    "api_id": "YOUR_API_ID",
    "api_hash": "YOUR_API_HASH"
  },
  "port": 8080,
  "session_name": "mcp_session"
}

環境變量

您也可以通過環境變量設置以下參數：

• TELEGRAM_API_ID：替換為您的api_id
• TELEGRAM_API_HASH：替換為您的api_hash
• PORT：服務器運行的端口，默認值為8080
• SESSION_NAME：會話名稱，默認值為mcp_session

運行

1. 手動啟動：

   node index.js
   

2. 使用PM2進行後臺運行：

   pm2 start index.js --save
   

故障排除

• 登錄提示：如果服務器在MCP客戶端啟動時持續請求登錄代碼/密碼，請確保data/session.json文件存在且有效。您可能需要手動運行node index.js以刷新會話。
• 緩存問題：如果頻道似乎過時或缺失，可以刪除./data/dialog_cache.json文件並重啟服務器（手動運行node index.js）以強制刷新。這可能會花費一些時間。
• 模塊找不到：確保在項目目錄中運行了npm install。如果MCP客戶端啟動服務器，請確保工作目錄設置正確或使用絕對路徑。

Telegram 客戶端庫

此倉庫還包含用於構建MCP服務器的底層telegram-client.js庫。有關詳細信息，請參閱LIBRARY.md。

📄 許可證

該項目根據MIT許可證發佈，具體見LICENSE文件。