Telegram MCP Server

🚀 Telegram MCP 服务器

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