电报-MCP服务器

Name: 电报-MCP服务器
Author: kfastov

作者：kfastov27 星标更新：2025-09-29

安装使用来源：spider==github.com

项目介绍

Telegram MCP 服务器

恢复更新（2025年9月）。 该服务器现在运行在官方的 @modelcontextprotocol/sdk 传输上，由 MtCute Telegram 客户端支持，并通过一个顺序后台归档工作者写入 SQLite。 重大变更。 MCP 客户端必须指向 http://localhost:8080/mcp；消息历史记录现在位于 data/messages.db，新的同步工具驱动归档任务。旧的实现作为分支 legacy-0.x 和标签 v0-legacy 发布，如果你需要旧的 /sse 流程。 关键变更： /mcp 端点，MtCute 会话处理，消息同步作业队列，SQLite 归档，client.js 中的新 CLI 辅助工具。

一个允许AI助手（如Claude或Cursor）使用用户客户端API（而不是机器人API）与你的Telegram账户交互的MCP服务器。该堆栈基于官方的 @modelcontextprotocol/sdk Streamable HTTP传输，并提供了面向Telegram的工具，用于列出对话、获取消息以及管理后台同步任务。

工具

工具	描述
`listChannels`	列出可用的对话/频道（可配置限制）。
`searchChannels`	按标题或用户名搜索对话。
`getChannelMessages`	获取最近的消息（ID或用户名，可选正则过滤器）。
`scheduleMessageSync`	调度一个后台作业以将对话归档到SQLite中。
`listMessageSyncJobs`	显示跟踪的同步作业、游标和状态。

先决条件

Node.js: 推荐使用18或更高版本。
Telegram 账户：
- 你需要一个有效的Telegram账户。
- 必须在账户上启用两步验证（2FA）（设置 → 隐私和安全 → 两步验证）。
Telegram API 凭证：
- 在https://core.telegram.org/api/obtaining_api_id创建一个新的应用程序以获得 api_id 和 api_hash。

安装

克隆此仓库：

git clone https://github.com/your-username/telegram-mcp-server.git # 替换为你的仓库URL
cd telegram-mcp-server

安装依赖项：
```
npm install
```

配置

需要设置两个独立的配置：

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 # 例如，+15551234567
```
将占位符值替换为您的实际凭证。
MCP 客户端配置：

修改客户端软件（如Claude Desktop、Cursor等）的配置文件以连接到MCP服务器：
```
{
  "mcpServers": {
    "telegram": {
    "url": "http://localhost:8080/mcp",
      "disabled": false,
      "timeout": 30
    }
  }
}
```
对于Claude Desktop，配置文件位于：
- 在macOS上：~/Library/Application Support/Claude/claude_desktop_config.json
- 在Windows上：%APPDATA%/Claude/claude_desktop_config.json
重要： 重启您的MCP客户端以应用更改。

运行服务器

运行服务器：
```
npm start
```
第一次运行时，服务器将通过MTProto进行身份验证。请输入来自Telegram的登录代码和（如果已启用）您的2FA密码。成功登录后，持久会话文件将保存在 ./data/session.json 下，除非会话被撤销，否则重启时不会再次提示。
将您的MCP客户端指向相同的URL。Cursor/Claude将发送标准的 initialize → notifications/initialized → tools/list 序列，SDK传输会自动处理。一旦连接，您应该能在客户端UI中看到Telegram工具集。

后台消息同步

作业和归档消息存储在 data/messages.db（SQLite）中。
服务器按顺序处理同步作业，并在请求之间等待以避免触发Telegram的速率限制。
使用MCP工具管理作业：
```
scheduleMessageSync { "channelId": -1001234567890 }
listMessageSyncJobs {}
```
您可以提供数字聊天ID或公共用户名作为 channelId。当服务器重启时，作业会自动恢复。作业状态从 pending → in_progress → idle 转移，如果需要重试，则转到 error。

故障排除

登录提示： 如果MCP客户端启动服务器时服务器不断提示登录代码/密码，请确保 data/session.json 文件存在且有效。您可能需要手动运行 npm start 一次以刷新会话。还要检查文件权限是否允许运行MCP客户端的用户读写 data 目录。
缓存问题： 如果频道看起来过时或丢失，请重新启动服务器；它将在启动时刷新聊天列表。
无法找到模块： 确保在项目目录中运行 npm install。如果MCP客户端启动服务器，请确保工作目录设置正确或使用绝对路径。
其他问题： 如果遇到其他问题，请随时在此服务器仓库中打开一个问题。

Telegram 客户端库

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

许可证

本项目根据MIT许可证发布 - 详情见LICENSE文件。