金大哥 - kfastov_telegram-mcp-server MCP 详情

article

README

🚀 Telegram 客户端库和 MCP 服务器

该项目提供了一个 Telegram 客户端库以及一个用于 AI 助手与 Telegram 交互的 MCP（模型上下文协议）服务器，能够帮助开发者便捷地实现 Telegram 相关功能，为 AI 助手与 Telegram 的交互搭建桥梁。

🚀 快速开始

本项目提供了 Telegram 客户端库和 MCP 服务器，以下是快速使用的步骤：

按照“安装指南”完成项目的安装配置。
根据“使用说明”使用 Telegram 客户端库和 MCP 服务器。
参考“API 参考”进行更深入的开发。

✨ 主要特性

Telegram 客户端库

身份验证：支持使用 Telegram 账号登录（包括双因素认证），保障登录的安全性。
会话管理：自动重用现有会话，提升使用效率。
获取对话/群组：检索所有对话和群组信息，方便用户全面了解。
获取消息：从特定群组或对话中获取消息，精准定位所需内容。
按模式过滤消息：使用正则表达式或其他规则筛选消息，快速找到目标信息。

MCP 服务器

搜索频道：通过关键词在频道名称中进行搜索，快速定位目标频道。
列出可用频道：查看所有可访问的频道，全面掌握资源。
获取频道消息：从任意可访问的频道中获取消息，满足信息获取需求。
按模式过滤消息：使用正则表达式对消息进行筛选，提高信息筛选效率。

📦 安装指南

创建一个 .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 服务器）

安装依赖：

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 服务器

启动 MCP 服务器：

npm start

MCP 服务器将运行在以下地址：

http://localhost:3000/mcp

您可以通过附带的客户端测试 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()：获取所有对话和群组信息
getMessageById(id)：通过 ID 获取特定消息
sendMessage(chatId, text)：向指定聊天发送消息
filterMessages(pattern)：按正则表达式过滤消息

文件结构

项目中的主要文件包括：

telegram-client.js：Telegram 客户端库的核心实现
mcp-server.js：MCP 服务器的主要逻辑
README.md：项目文档和使用说明
.env：环境变量配置文件
package.json：项目依赖管理文件

集成与扩展

该库设计用于与其他 AI 助手（如 Claude）集成，允许这些助手通过 Telegram 进行交互并处理消息。您可以通过自定义逻辑扩展其功能。

📄 许可证

本项目使用 MIT 许可证，详情请参阅 LICENSE 文件。

kfastov_telegram-mcp-server