Kfastov Telegram MCP Server

🚀 Telegram 客戶端庫和 MCP 服務器

本項目提供了一個 Telegram 客戶端庫，以及一個用於 AI 助手與 Telegram 進行交互的 MCP（模型上下文協議）服務器，能助力開發者更便捷地實現與 Telegram 的交互功能。

🚀 快速開始

本項目包含 Telegram 客戶端庫和 MCP 服務器，下面為你介紹如何快速使用。

✨ 主要特性

Telegram 客戶端庫

• 身份驗證：支持使用 Telegram 賬號登錄，包含雙因素認證功能，保障登錄安全。
• 會話管理：可自動重用現有會話，提升使用效率。
• 獲取對話/群組：能檢索所有對話和群組的詳細信息。
• 獲取消息：可從特定群組或對話中精準獲取消息。
• 按模式過濾消息：支持使用正則表達式或其他規則篩選消息，滿足多樣化需求。

MCP 服務器

• 搜索頻道：可通過關鍵詞在頻道名稱中進行搜索，快速定位目標頻道。
• 列出可用頻道：能查看所有可訪問的頻道，一覽無餘。
• 獲取頻道消息：可從任意可訪問的頻道中獲取消息。
• 按模式過濾消息：使用正則表達式對消息進行篩選，精準獲取所需內容。

📦 安裝指南

1. 創建一個 .env 文件，並添加您的 Telegram API 憑證：

TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
TELEGRAM_PHONE_NUMBER=your_phone_number
PORT=3000  # 可選，默認為 3000（MCP 服務器）

2. 安裝依賴：

npm install

💻 使用示例

基礎用法

使用 Telegram 客戶端庫

const TelegramClient = require("./telegram-client");
const dotenv = require("dotenv");

dotenv.config();

async function main() {
  // 創建一個新的客戶端實例
  const client = new TelegramClient(
    process.env.TELEGRAM_API_ID,
    process.env.TELEGRAM_API_HASH,
    process.env.TELEGRAM_PHONE_NUMBER
  );

  // 登錄到 Telegram
  await client.login();

  // 獲取所有對話/群組
  const { chats } = await client.getDialogs();

  // 打印所有對話/群組信息
  chats.forEach((chat) => {
    if (chat.title) {
      console.log(`對話：${chat.title}`);
    }
  });
}

main().catch(console.error);

運行示例客戶端：

npm run client

使用 MCP 服務器

1. 啟動 MCP 服務器：

npm start

2. MCP 服務器將運行在以下地址：

http://localhost:3000/mcp

3. 您可以通過附帶的客戶端測試 MCP 服務器：

npm run mcp-client

有關 MCP 服務器的詳細信息，請參閱 MCP-README.md。
有關代碼結構，請參閱 CODE_STRUCTURE.md。

📚 詳細文檔

TelegramClient

構造函數

const client = new TelegramClient(apiId, apiHash, phoneNumber, sessionPath);

• apiId：您的 Telegram API ID
• apiHash：您的 Telegram API Hash
• phoneNumber：您的電話號碼（國際格式）
• sessionPath：（可選）存儲會話文件的路徑（默認： './data/session.json'）

方法

• login()：登錄到 Telegram 賬號
• getDialogs()：獲取所有對話和群組信息
• getMessageById(id)：通過 ID 獲取特定消息
• sendMessage(chatId, text)：向指定聊天發送消息
• filterMessages(pattern)：按正則表達式過濾消息

文件結構

項目中的主要文件包括：

1. telegram-client.js：Telegram 客戶端庫的核心實現
2. mcp-server.js：MCP 服務器的主要邏輯
3. README.md：項目文檔和使用說明
4. .env：環境變量配置文件
5. package.json：項目依賴管理文件

集成與擴展

該庫設計用於與其他 AI 助手（如 Claude）集成，允許這些助手通過 Telegram 進行交互並處理消息。您可以通過自定義邏輯擴展其功能。

📄 許可證

本項目使用 MIT 許可證，詳情請參閱 LICENSE 文件。