Telegram 客户端库和 MCP 服务器

该项目同时提供了一个 Telegram 客户端库 (telegram-client.js) 和一个 MCP（模型上下文协议）服务器 (mcp-server.js)，使 AI 助手（如 Claude、Cline 或 Cursor）能够通过用户客户端 API（而非 bot API）与 Telegram 进行交互。这使得从频道和聊天中读取消息历史记录成为可能，并且在未来更新中有可能代表用户发送消息。服务器组件是使用 FastMCP 库构建的。

特性

Telegram 客户端库 (telegram-client.js)

• 支持与 Telegram 的认证（包括双因素认证支持）
• 会话管理（自动重用现有会话）
• 获取聊天/对话（带缓存）
• 从特定聊天中获取消息（使用缓存的 ID）
• 按模式过滤消息（例如，正则表达式）

MCP 服务器 (mcp-server.js)

• 为 AI 代理提供 MCP 工具：
  • listChannels: 列出缓存的频道/聊天。
  • searchChannels: 根据关键词搜索缓存的频道/聊天。
  • getChannelMessages: 使用其 ID 从特定频道/聊天中检索消息，可选正则表达式过滤。
• 通过 Server-Sent Events (SSE) 上的模型上下文协议进行通信。
• 初始化并维护一个 Telegram 对话缓存 (./data/dialog_cache.json)，以加快响应速度并减少 API 调用次数。

设置

1. 创建一个包含您的 Telegram API 凭证的 .env 文件：

   TELEGRAM_API_ID=your_api_id
   TELEGRAM_API_HASH=your_api_hash
   TELEGRAM_PHONE_NUMBER=your_phone_number
   # PORT=8080 # 可选：如果此处未设置或代码中未覆盖，则 MCP 服务器默认为 8080 端口
   

2. 安装依赖项：

   npm install
   

使用方法

使用 Telegram 客户端库 (telegram-client.js)

该库允许直接编程方式与 Telegram 进行交互。

// Example using the client library (see client.js for a more complete example)
import TelegramClient from "./telegram-client.js";
import dotenv from "dotenv";

dotenv.config();

async function main() {
  // Create a new client instance
  const client = new TelegramClient(
    process.env.TELEGRAM_API_ID,
    process.env.TELEGRAM_API_HASH,
    process.env.TELEGRAM_PHONE_NUMBER
    // Optional: specify session path, default is './data/session.json'
  );

  // Login to Telegram (will prompt for code/password if needed)
  await client.login();

  // Load dialog cache (optional, but recommended for performance)
  // Or use getAllDialogs() to fetch and populate the cache
  await client.loadDialogCache(); // Default path: './data/dialog_cache.json'
  if (client.dialogCache.size === 0) {
    console.log("Cache empty, fetching all dialogs to build cache...");
    await client.getAllDialogs(); // Fetches all dialogs and populates cache
    await client.saveDialogCache(); // Save cache for next time
  }

  // Get dialogs from the cache
  const dialogs = Array.from(client.dialogCache.values());

  // Print all cached chats
  dialogs.forEach((chat) => {
    if (chat.title) {
      console.log(`Chat: ${chat.title} (ID: ${chat.id})`);
    }
  });

  // Example: Get messages (replace 'your_channel_id' with an actual ID from the cache)
  // const messages = await client.getMessagesByChannelId('your_channel_id', 50);
  // console.log(messages);
}

main().catch(console.error);

运行独立客户端示例：

node client.js

使用 MCP 服务器 (mcp-server.js)

此服务器将 Telegram 交互作为工具暴露给支持 MCP 的 AI 助手（如 Claude）。

1. 启动 MCP 服务器：
   (首先，请确保您至少已经通过客户端登录过一次，或者之前运行过服务器，从而创建了 ./data/session.json 文件)

   npm start
   

2. 服务器将初始化 Telegram 客户端并尝试加载/构建对话缓存 (./data/dialog_cache.json)。首次运行时可能需要一些时间。

3. MCP 服务器端点将通过 Server-Sent Events (SSE) 在以下地址可用：

   http://localhost:8080/sse
   

4. 您可以将兼容 MCP 的客户端（如 AI 助手）连接到此端点。

API 参考 (telegram-client.js)

TelegramClient

构造函数

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

• apiId: 您的 Telegram API ID
• apiHash: 您的 Telegram API Hash
• phoneNumber: 国际格式的电话号码
• sessionPath: （可选）保存会话文件的路径（默认：'./data/session.json'）

方法

• login(): 通过 Telegram 进行身份验证（处理新登录、双因素认证和会话重用）。
• hasSession(): 检查是否存在有效的会话文件。
• getDialogs(limit, offset): 直接从 Telegram API 获取一批对话（聊天）。
• getAllDialogs(batchSize): 逐步获取所有对话，并填充内部缓存 (dialogCache)。
• _updateDialogCache(chats): 更新缓存的内部方法。
• getPeerInputById(id): 从缓存中获取用于 API 调用所需的 InputPeer 对象。
• getChatMessages(chatObject, limit): 从特定的聊天对象获取消息（现在较少使用）。
• getMessagesByChannelId(channelId, limit): 使用 ID 从特定的聊天/频道获取消息（使用缓存的 peer 信息）。
• filterMessagesByPattern(messages, pattern): 通过正则表达式模式过滤消息字符串数组。
• saveDialogCache(cachePath): 将内部 dialogCache 映射保存到 JSON 文件中（默认为 ./data/dialog_cache.json）。
• loadDialogCache(cachePath): 从 JSON 文件加载 dialogCache 映射。

本仓库中的文件

• client.js: 一个示例脚本，演示如何使用 telegram-client.js 库。
• telegram-client.js: 核心的 Telegram 客户端库，处理身份验证和 API 交互。
• mcp-server.js: MCP 服务器实现（使用 FastMCP），通过 SSE 提供 Telegram 工具。

与 Claude 或其他支持 MCP 的助手一起使用

MCP 服务器 (mcp-server.js) 可以与 Claude 或其他支持通过 Server-Sent Events (SSE) 的 Model Context Protocol 的助手一起使用。

示例工作流程：

1. 启动 MCP 服务器 (npm start)。
2. 使用 SSE 端点将 Claude（或其他助手）连接到 MCP 服务器：http://localhost:8080/sse。
3. 助手现在可以使用可用的工具：
   • listChannels
   • searchChannels
   • getChannelMessages（可选地带有 filterPattern）

与 Claude 的示例交互

当连接到 MCP 服务器时，您可以向 Claude 提出自然语言问题，例如：

• "显示所有可用的 Telegram 频道"
• "搜索关于加密货币的频道"
• "从频道 1234567890 获取最后 10 条消息"
• "在 CryptoFrog 频道中查找包含 UUID 的消息"

高级用法

使用正则表达式过滤消息

您可以使用 filterPattern 参数与 getChannelMessages 一起查找特定类型的消息。一些示例：

• [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12} - 查找 UUID
• https?://\\S+ - 查找 URL
• #[a-zA-Z0-9]+ - 查找标签

故障排除

• 身份验证问题：如果您遇到身份验证问题，请删除 data/ 目录中的会话文件并重新启动服务器以重新进行身份验证。
• 服务器崩溃：检查您的环境变量并确保您的 Telegram API 凭证正确无误。
• 访问频道被拒绝：确保您的 Telegram 账户有权访问您试图查询的频道。

许可证

请根据实际需要添加许可证内容。

此项目采用 MIT 许可证进行授权 - 详情请参阅 LICENSE 文件。