🚀 Telegram MCP 服务器

Telegram MCP 服务器用于通过 Model Context Protocol (MCP) 与 Telegram API 进行交互，允许 AI 代理和其他 MCP 客户端与 Telegram 进行互动。

🚀 快速开始

本服务器允许 AI 代理和其他 MCP 客户端与 Telegram 互动。若要使用该服务器，需完成安装、配置和运行等步骤。

✨ 主要特性

• 支持 AI 代理和 MCP 客户端与 Telegram 交互。
• 提供多种工具，如 executeCode、getFiles 等。
• 支持在 Cursor 和 Claude Desktop 中集成。

📦 安装指南

要求

• Node.js 14+（或更高版本）
• npm
• Telegram 的 API ID 和 API 哈希

安装步骤

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 哈希： 请参阅 如何获取 Telegram 的 API ID 和 API 哈希。

💻 使用示例

基础用法

// 示例：获取更新
await executeTool({
  toolName: "getUpdates",
  parameters: {
    offset: null,
    limit: 10,
    timeout: 0
  }
});

📚 详细文档

运行

1. 安装完成后，从项目根目录运行服务器：

   npm run mcp
   

   第一次运行时，系统会提示你输入 Telegram 账户的电话号码、2FA 密码（如果有）、Telegram 密码（如果有）。

集成

在 Cursor 中集成

1. 打开 Cursor 并转到 设置。
2. 进入 MCP 服务器 部分。
3. 点击 添加 MCP 服务器，输入以下信息：
   • 名称：Telegram
   • 类型：URL
   • 地址：http://localhost:3000

在 Claude Desktop 中集成

1. 打开 Claude Desktop 并转到 设置。
2. 进入 MCP 服务器 部分。
3. 点击 添加 MCP 服务器，输入以下信息：
   • 名称：Telegram
   • 类型：URL
   • 地址：http://localhost:3000

功能检查

• 运行服务器后，可以通过访问 http://localhost:3000 测试 MCP 服务器。

可用工具

以下是 MCP 服务器支持的工具列表：

1. executeCode
2. getFiles
3. getGptModels
4. getImages
5. getUpdates
6. initialize
7. setOptions

授权

• 第一次运行时，系统会提示你输入 Telegram 账户的电话号码、2FA 密码（如果有）、Telegram 密码（如果有）。
• 如果授权失败，可以删除 sessions/ 目录中的 session 文件并重新尝试。

会话文件结构

会话文件存储在 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 和哈希。
• 在受信任的环境中运行服务器。
• 会话文件包含敏感数据。请妥善保管，并不要分享。
• executeMethod 工具可以执行任何 Telegram API 方法。使用时要谨慎，因为它可能会执行破坏性操作。

📄 许可证

本项目采用 MIT 许可证。