Telegram

Telegram MCP 服务

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

通过模型上下文协议（MCP）与 Telegram API 交互的服务。允许 AI Agent 和其他 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 文件：

   # Copy the example .env file
   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    # Run from the project root directory

选项 2：直接通过 node 执行

# Run from the project root directory
node mcp-server.js

选项 3：作为可执行文件运行

# From the project root
./mcp-server.js

选项 4：全局安装后运行

npm install -g .   # Install the package globally
telegram-mcp       # Run the globally installed package

与 MCP 客户端集成

在 Cursor 中配置

1. 打开 Cursor 设置
2. 前往 Features -> MCP Servers
3. 点击“Add new MCP server”
4. 配置服务：
   • 名称：telegram（或其他名称）
   • 类型：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. 配置服务：
   • 名称：telegram（或其他名称）
   • 类型：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）。

提示词中的使用示例

Using the telegram.getDialogs tool for session +79001234567, show me the last 5 chats.

With telegram.sendMessage for session +79001234567, send the message "Hello from my AI assistant!" to chat with ID 'username_or_chat_id'.

授权

首次使用某个 session（电话号码）时，服务会在其运行所在的控制台中请求输入确认码。输入从 Telegram 收到的代码即可授权该会话。

如果启用了双重身份验证（2FA），还需要输入 Telegram 密码。如果密码输入错误，系统会提示重新输入（最多 3 次）。

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

会话文件结构

会话以 JSON 文件的形式存储在 sessions/ 目录中，文件名为电话号码（例如：+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