Telegram 客户端库和 MCP 服务器

本项目提供了一个 Telegram 客户端库和一个 MCP (模型上下文协议) 服务器，供 AI 助手与 Telegram 交互。

功能

Telegram 客户端库

• Telegram 身份验证（包括 2FA 支持）
• 会话管理（自动重用现有会话）
• 检索聊天/对话
• 从特定聊天中获取消息
• 按模式过滤消息（例如，正则表达式）

MCP 服务器

• 按关键字搜索频道 - 通过搜索频道名称中的关键字来查找 Telegram 频道
• 列出可用频道 - 查看所有可访问的频道
• 从频道获取消息 - 从任何可访问的频道检索消息
• 按模式过滤消息 - 应用正则表达式模式来过滤消息

设置

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

TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
TELEGRAM_PHONE_NUMBER=your_phone_number
PORT=3000  # 可选，MCP 服务器默认为 3000

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: ${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。

API 参考

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(limit, offset): 获取对话（聊天）列表
• getChatMessages(chat, limit): 从特定聊天中获取消息
• filterMessagesByPattern(messages, pattern): 通过正则表达式模式过滤消息数组
• hasSession(): 检查是否存在有效的会话

本仓库中的文件

• telegram-client.js: 主要客户端库
• client.js: 带有附加辅助函数的示例客户端
• index.js: 使用客户端库的原始示例
• mcp-server.js: MCP 服务器主入口点
• telegram-mcp.js: 带有 Telegram 工具的 MCP 服务器实现
• http-server.js: HTTP/SSE 服务器传输层
• mcp-client-example.js: 用于测试 MCP 服务器的简单客户端

与 Claude 或其他 MCP 兼容的助手一起使用

MCP 服务器可以与 Claude 或其他 MCP 兼容的助手一起使用。 连接后，助手将可以通过服务器提供的工具访问您的 Telegram 频道和消息。

示例工作流程：

1. 启动 MCP 服务器
2. 使用 MCP URL 将 Claude 连接到 MCP 服务器
3. 要求 Claude 搜索频道、检索消息或按模式过滤消息

许可证

MIT