Telegram MCP 服务器

English version | Русская версия

用于通过模型上下文协议 (MCP) 处理 Telegram API 的服务器。允许 AI 代理和其他 MCP 客户端与 Telegram 交互。

要求

• Node.js 14+ (或更高版本)
• npm
• 来自 Telegram 的 API ID 和 API Hash

安装

1. 克隆存储库：

   git clone https://github.com/kdoronin/telegram_mcp
   cd telegram-mcp
   

2. 安装依赖项：

   npm install
   

   (这将安装必要的软件包：gramjs、@modelcontextprotocol/sdk、zod 等。)

3. 创建并配置 .env 文件：

   # 复制示例 .env 文件
   cp .env.example .env
   

   编辑 .env 文件并指定您的 API_ID 和 API_HASH。

4. 获取 API ID 和 API Hash：

   • 前往 my.telegram.org
   • 登录您的帐户
   • 导航到 "API development tools"
   • 创建一个新的应用程序
   • 将 api_id 和 api_hash 复制到您的 .env 文件

运行

关于运行的重要说明

主服务器文件 mcp-server.js 位于项目根目录中，这允许在没有路径问题的情况下运行它。

选项 1：通过 npm (推荐)

npm run mcp    # 从项目根目录运行

选项 2：直接 node 执行

# 从项目根目录运行
node mcp-server.js

选项 3：作为可执行文件

# 从项目根目录
./mcp-server.js

选项 4：全局安装后

npm install -g .   # 全局安装该包
telegram-mcp       # 运行全局安装的包

与 MCP 客户端集成

在 Cursor 中配置

1. 打开 Cursor 设置
2. 转到 Features -> MCP Servers
3. 点击 "Add new MCP server"
4. 配置服务器：
   • Name: telegram (或任何其他名称)
   • Type: command
   • Command: node /full/path/to/project/mcp-server.js
   • 或者: npx telegram-mcp (全局安装后)

在 Claude Desktop 中配置

1. 打开 Claude Desktop 设置
2. 转到 Tools -> MCP
3. 点击 "Add New Server"
4. 配置服务器：
   • Name: telegram (或任何其他名称)
   • Type: command
   • Command: node /full/path/to/project/mcp-server.js
   • 或者: npx telegram-mcp (全局安装后)

检查功能

当服务器启动时：

1. 它将从 .env 文件加载设置
2. 检查已保存的会话
3. 如果没有会话，它将提供创建一个新会话（您需要输入电话号码和验证码）

可用工具

MCP 服务器提供以下工具：

• getDialogs: 获取用户对话（聊天）列表。
  • 参数：session (字符串，必需), limit (整数，可选，默认值：100)。
• getMessages: 获取指定聊天的消息。
  • 参数：session (字符串，必需), chatId (字符串，必需), limit (整数，可选，默认值：100)。
• sendMessage: 向指定聊天发送消息。
  • 参数：session (字符串，必需), chatId (字符串，必需), message (字符串，必需)。
• executeMethod: 执行任意 Telegram API 方法（谨慎使用）。
  • 参数：session (字符串，必需), method (字符串，必需), params (对象，可选)。

注意：session 参数通常是用户的国际格式电话号码（例如，+79001234567）。

提示中的使用示例

使用 telegram.getDialogs 工具，会话为 +79001234567，显示最近的 5 个聊天。

使用 telegram.sendMessage 工具，会话为 +79001234567，向 ID 为 'username_or_chat_id' 的聊天发送消息 "Hello from my AI assistant!"。

授权

首次使用 session（电话号码）时，服务器将在运行它的控制台中请求验证码。 输入从 Telegram 收到的代码以授权会话。

如果您启用了双重身份验证 (2FA)，您还需要输入您的 Telegram 密码。 如果密码输入不正确，系统将提示您再次输入（最多 3 次尝试）。

成功授权后，会话将保存到 sessions/ 目录中的文件中，并将用于后续请求。

会话文件结构

会话存储在 sessions/ 目录中，作为以电话号码命名的 JSON 文件（例如，+79001234567.json）。 每个文件包含：

• 会话字符串（加密的授权令牌）
• 创建/更新的时间戳

故障排除

1. 错误 "Your API ID or Hash cannot be empty or undefined"

   • 检查 .env 文件是否位于项目根目录中
   • 确保 API_ID 和 API_HASH 在其中正确指定
   • 从项目根目录运行服务器

2. 服务器看不到已保存的会话

   • 检查执行路径（应来自项目根目录）
   • 检查 sessions/ 目录中是否存在会话文件
   • 尝试使用 npm run mcp 运行

3. 授权错误

   • 如果您输入了不正确的 2FA 密码，系统将提示您重新输入
   • 如果所有尝试都已用尽，请删除会话文件并重试

安全

• 不要与第三方分享您的 API ID 和 API Hash。
• 在受信任的环境中运行服务器。
• 会话文件包含敏感数据。 将它们存储在安全的位置，不要分享它们。
• executeMethod 工具允许执行任何 Telegram API 方法。 谨慎使用，因为它可能会执行破坏性操作。

许可证

MIT