JinDaGe - telegram MCP Details

article

README

🚀 Telegram MCP 服务器

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

🚀 快速开始

本服务器允许 AI 代理和其他 MCP 客户端与 Telegram 进行互动。以下是使用该服务器的快速步骤：

确保满足运行要求。
完成服务器的安装。
运行服务器并进行集成。
检查功能并进行授权。

✨ 主要特性

支持 AI 代理和其他 MCP 客户端与 Telegram 互动。
提供多种工具，如 executeCode、getFiles 等。

📦 安装指南

要求

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

安装步骤

克隆仓库：

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

安装依赖项：
```
npm install
```
(这将安装必要的包：gramjs，@modelcontextprotocol/sdk，zod 等。)
创建并配置 .env 文件：
```
# 复制示例 .env 文件
cp .env.example .env
```
编辑 .env 文件并在其中指定你的 API_ID 和 API_HASH。
获取 API ID 和 API 哈希：请参阅如何获取 Telegram 的 API ID 和 API 哈希。

💻 使用示例

基础用法

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

📚 详细文档

运行

安装完成后，从项目根目录运行服务器：
```
npm run mcp
```
第一次运行时，系统会提示你输入 Telegram 账户的电话号码、2FA 密码（如果有）、Telegram 密码（如果有）。

集成

在 Cursor 中集成

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

在 Claude Desktop 中集成

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

功能检查

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

可用工具

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

executeCode
getFiles
getGptModels
getImages
getUpdates
initialize
setOptions

授权

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

会话文件结构

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

加密的会话字符串
创建/更新时间戳

故障排除

错误 "Your API ID or Hash cannot be empty or undefined"
- 检查 .env 文件是否在项目根目录中
- 确保 API_ID 和 API_HASH 正确填写
- 从项目根目录运行服务器
服务器未识别保存的会话
- 检查执行路径（应为项目根目录）
- 检查 sessions/ 目录中的会话文件是否存在
- 尝试使用 npm run mcp 运行
授权错误
- 如果输入了错误的 2FA 密码，系统会让你重新输入
- 如果所有尝试都失败，删除会话文件并重试

安全提示

⚠️ 重要提示

请勿与第三方共享你的 API ID 和哈希。

在受信任的环境中运行服务器。

会话文件包含敏感数据，请妥善保管，并不要分享。

executeMethod 工具可以执行任何 Telegram API 方法。使用时要谨慎，因为它可能会执行破坏性操作。

📄 许可证

本项目采用 MIT 许可证。

telegram