Telegram MCP Server

🚀 Telegram MCP 服务器

这是一个MCP（Multipurpose Control Protocol）服务器，它能让AI助手（像Claude这类）借助用户客户端API（而非机器人API）与您的Telegram账户进行交互。此服务器是基于@mtproto/core和FastMCP框架搭建而成。

🚀 快速开始

若要使用此Telegram MCP服务器，您需要完成一系列准备步骤，包括安装必要的软件、获取相关凭证、配置服务器等。以下为您详细介绍操作流程：

1. 安装先决条件：
   • 确保您已安装Node.js，推荐使用版本18或更高。
   • 准备一个活跃的Telegram账户，并启用两步验证（2FA）（设置 → 隐私与安全 → 两步验证）。
   • 在此处获取api_id和api_hash。
2. 克隆仓库并安装依赖：

   git clone https://github.com/kfastov/telegram-mcp-server.git
   cd telegram-mcp-server
   npm install
   

3. 配置服务器：
   • 编辑config.json文件，设置相关参数，示例如下：

   {
     "telegram": {
       "api_id": "YOUR_API_ID",
       "api_hash": "YOUR_API_HASH"
     },
     "port": 8080,
     "session_name": "mcp_session"
   }
   

   • 您也可以通过环境变量设置参数，如TELEGRAM_API_ID、TELEGRAM_API_HASH、PORT和SESSION_NAME。
4. 运行服务器：
   • 手动启动：

   node index.js
   

   • 使用PM2进行后台运行：

   pm2 start index.js --save
   

✨ 主要特性

工具

• listChannels
  • 功能：基于服务器缓存，列出当前账户可访问的Telegram频道/聊天。
  • 参数：
    • limit (number, optional)：返回的最大频道数，默认值为50。
  • 输出：包含ID、标题、类型和接入哈希（如有适用）的频道/聊天列表。
• searchChannels
  • 功能：根据名称中的关键字搜索缓存中的频道/聊天。
  • 参数：
    • keywords (string)：在频道名称中搜索的关键字。
    • limit (number, optional)：返回的最大结果数，默认值为100。
  • 输出：匹配的频道/聊天列表。
• getChannelMessages
  • 功能：使用其ID从特定频道/聊天中检索最近的消息。
  • 参数：
    • channelId (number)：频道/聊天的数字ID（通过listChannels或searchChannels获得）。
    • limit (number, optional)：返回的最大消息数，默认值为100。
    • filterPattern (string, optional)：用于根据文本内容过滤消息的JavaScript兼容正则表达式。
  • 输出：包含ID、日期、文本和发送者ID的消息列表。

📦 安装指南

1. 克隆此仓库：

   git clone https://github.com/kfastov/telegram-mcp-server.git
   cd telegram-mcp-server
   

2. 安装依赖项：

   npm install
   

📚 详细文档

配置

服务器配置

编辑config.json文件，设置以下参数：

{
  "telegram": {
    "api_id": "YOUR_API_ID",
    "api_hash": "YOUR_API_HASH"
  },
  "port": 8080,
  "session_name": "mcp_session"
}

环境变量

您也可以通过环境变量设置以下参数：

• TELEGRAM_API_ID：替换为您的api_id
• TELEGRAM_API_HASH：替换为您的api_hash
• PORT：服务器运行的端口，默认值为8080
• SESSION_NAME：会话名称，默认值为mcp_session

运行

1. 手动启动：

   node index.js
   

2. 使用PM2进行后台运行：

   pm2 start index.js --save
   

故障排除

• 登录提示：如果服务器在MCP客户端启动时持续请求登录代码/密码，请确保data/session.json文件存在且有效。您可能需要手动运行node index.js以刷新会话。
• 缓存问题：如果频道似乎过时或缺失，可以删除./data/dialog_cache.json文件并重启服务器（手动运行node index.js）以强制刷新。这可能会花费一些时间。
• 模块找不到：确保在项目目录中运行了npm install。如果MCP客户端启动服务器，请确保工作目录设置正确或使用绝对路径。

Telegram 客户端库

此仓库还包含用于构建MCP服务器的底层telegram-client.js库。有关详细信息，请参阅LIBRARY.md。

📄 许可证

该项目根据MIT许可证发布，具体见LICENSE文件。