Telegram MCP 服务器

一个MCP（Multipurpose Control Protocol）服务器，允许AI助手（如Claude）通过用户客户端API（而非机器人API）与您的Telegram账户交互。该服务器基于@mtproto/core和FastMCP框架构建。

特性

工具

• 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. Node.js: 推荐使用版本18或更高。
2. Telegram账户:
   • 您需要一个活跃的Telegram账户。
   • 必须启用两步验证（2FA）（设置 → 隐私与安全 → 两步验证）。
3. Telegram API凭证:
   • 在此处获取api_id和api_hash。

安装

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