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 文件。