Telegram MCP Server

Telegram MCP 服务器

一个 MCP 服务器，允许 AI 助手（例如 Claude）使用用户客户端 API（而非机器人 API）与您的 Telegram 帐户进行交互。基于@mtproto/core和FastMCP框架构建。

特征

工具

• listChannels
  • 根据服务器的缓存，列出帐户可访问的电报频道/聊天。
  • 参数：
    • limit （数字，可选）：返回的最大通道数（默认值：50）。
  • 输出：频道/聊天列表及其 ID、标题、类型和访问哈希（如果适用）。
• searchChannels
  • 通过名称中的关键字搜索缓存的频道/聊天。
  • 参数：
    • keywords （字符串）：在频道名称中搜索的关键字。
    • limit （数字，可选）：返回的最大结果数（默认值：100）。
  • 输出：匹配的频道/聊天列表。
• getChannelMessages
  • 使用其 ID 从特定频道/聊天中检索最新消息。
  • 参数：
    • channelId （数字）：频道/聊天的数字 ID（从listChannels或searchChannels获取）。
    • limit （数字，可选）：返回的最大消息数（默认值：100）。
    • filterPattern （字符串，可选）：与 JavaScript 兼容的正则表达式，用于根据文本内容过滤消息。
  • 输出：包含 ID、日期、文本和发件人 ID 的消息列表。

先决条件

1. **Node.js：**建议使用 18 或更高版本。
2. 电报账户：
   • 您需要一个活跃的 Telegram 帐户。
   • 您的帐户必须启用两步验证 (2FA) （设置 → 隐私和安全 → 两步验证）。
3. 电报 API 凭证：
   • 通过在https://core.telegram.org/api/obtaining_api_id创建新应用程序来获取api_id和api_hash 。

安装

1. 克隆此存储库：
   git clone https://github.com/your-username/telegram-mcp-server.git # Replace with your repo URL cd telegram-mcp-server
2. 安装依赖项：
   npm install

配置

有两个单独的配置需要设置：

1. MCP 服务器配置：使用环境变量配置 Telegram MCP 服务器（在.env文件中或直接在您的环境中）：
   TELEGRAM_API_ID=YOUR_API_ID TELEGRAM_API_HASH=YOUR_API_HASH TELEGRAM_PHONE_NUMBER=YOUR_PHONE_NUMBER_WITH_COUNTRY_CODE # e.g., +15551234567
   将占位符值替换为您的实际凭证。
2. MCP 客户端配置：通过修改配置文件来配置客户端软件（Claude Desktop、Cursor 等）连接到 MCP 服务器：
   { "mcpServers": { "telegram": { "url": "http://localhost:8080/sse", "disabled": false, "timeout": 30 } } }
   对于 Claude Desktop，配置文件位于：
   • 在 macOS 上： ~/Library/Application Support/Claude/claude_desktop_config.json
   • 在 Windows 上： %APPDATA%/Claude/claude_desktop_config.json

   **重要提示：**重新启动 MCP 客户端以应用更改。

运行服务器

1. **初始登录（重要的第一步）：**首次运行服务器时（或者会话过期/无效），需要通过 Telegram 进行身份验证。请直接从终端运行：
   npm start
   • 服务器将使用来自您的.env文件的凭据。
   • 它会提示您在终端中输入发送到您的 Telegram 帐户的登录代码和您的 2FA 密码（如果需要）。
   • 成功登录后，将创建一个会话文件 ( ./data/session.json )。此文件允许服务器将来自动登录，而无需输入代码/密码。
   • 服务器还会尝试构建或加载您的聊天记录缓存 ( ./data/dialog_cache.json )。首次运行时可能需要一些时间，尤其是在聊天记录较多的情况下。如果缓存已存在，后续启动速度会更快。
2. **正常操作：**您需要通过在项目目录中运行npm start手动启动服务器。一旦服务器运行，您的 MCP 客户端（例如，Claude Desktop）将通过其配置中指定的 URL 连接到它（默认情况下为http://localhost:8080/sse ）。

故障排除

• **登录提示：**如果 MCP 客户端启动服务器时，服务器不断提示输入登录代码/密码，请确保data/session.json文件存在且有效。您可能需要手动运行npm start一次来刷新会话。此外，请检查文件权限是否允许运行 MCP 客户端的用户读取/写入data目录。
• **缓存问题：**如果频道似乎已过期或缺失，您可以删除./data/dialog_cache.json并重启服务器（手动运行npm start ）以强制完全刷新。这可能需要一些时间。
• **找不到模块：**请确保在项目目录中运行npm install 。如果 MCP 客户端启动了服务器，请确保工作目录设置正确或使用绝对路径。
• **其他问题：**如果您遇到任何其他问题，请随时在此服务器存储库中打开问题。

Telegram 客户端库

此仓库还包含 MCP 服务器使用的底层telegram-client.js库。有关直接使用该库的详细信息（例如，用于自定义脚本），请参阅LIBRARY.md 。

执照

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。