内容
云服务
[](./LICENSE)
[](https://mcp-telegram.com)
开源的 MCP 服务器，通过 OAuth 和二维码登录将 Telegram 账户连接到 AI 助手（Claude.ai, ChatGPT）。免费托管在 [mcp-telegram.com](https://mcp-telegram.com)，或在您自己的基础设施上自行托管。
这是 **云/多用户** 版本。对于单用户 CLI（stdio 传输，全读+写，所有 MTProto 工具），请使用上游的 [`@overpod/mcp-telegram`](https://github.com/mcp-telegram/mcp-telegram)。
## 功能介绍
- 通过 Streamable HTTP 将 Telegram 账户暴露给支持 MCP 的客户端（Claude.ai, ChatGPT 应用，自定义 MCP 主机）。
- **仅限只读和安全状态变更工具** —— 没有 `send-message`，没有 `delete-message`，没有管理员操作。托管服务在功能和影响范围之间取得平衡。
- OAuth 2.0，带有动态客户端注册和 PKCE（RFC 8414 + 7591 + 7636）。二维码登录嵌入在 OAuth 授权页面中 —— 连接一次，通过刷新令牌重新连接 30 天。
## 快速开始（托管服务）
1. 打开 Claude.ai → 设置 → 连接器 → **添加自定义连接器**。
2. 服务器 URL：`https://mcp-telegram.com/mcp`。
3. 点击连接。您将被重定向到使用 Telegram 扫描二维码（设置 → 设备 → 链接桌面设备）。
4. 完成。询问 Claude 读取您的未读消息，搜索聊天等。
ChatGPT 应用目录提交正在审核中。在此期间，请在 ChatGPT 中手动添加 `https://mcp-telegram.com/mcp` 作为自定义 MCP 服务器。
## 快速开始（自行托管）
```bash
git clone https://github.com/mcp-telegram/mcp-telegram-cloud.git
cd mcp-telegram-cloud
cp .env.example .env
# 填写 TELEGRAM_API_ID + TELEGRAM_API_HASH（来自 https://my.telegram.org/apps）
# 和 ISSUER（您的公共 HTTPS URL）。ADMIN_TOKEN 是可选的，但建议使用 ——
# 没有它，/api/* 上的管理员操作（统计信息，操作员端会话导入）将返回 401。
docker compose -f docker-compose.example.yml up -d --build
```
示例 compose 文件绑定到 `127.0.0.1:3000`，**不包括 TLS 终止**。OAuth 客户端需要 HTTPS，因此请在前面添加反向代理（Traefik，nginx + certbot，Caddy，托管 LB）。有关威胁模型，强化检查清单和事件响应，请参阅 [`docs/self-hosting.md`](./docs/self-hosting.md)。
> ⚠️ 会话数据库以明文存储活动 MTProto 会话字符串。请在生产环境中使用前阅读 [`docs/self-hosting.md`](./docs/self-hosting.md) §威胁模型。
## MCP 工具列表
云服务白名单了一部分上游工具。所有工具都标注为 `readOnlyHint: true` 或是安全状态变更（标记为已读，静音）。
**读取和搜索**
- `telegram-status` — 连接状态
- `telegram-list-chats` — 带过滤的对话列表
- `telegram-read-messages` — 分页消息读取
- `telegram-search-chats` — 按名称/描述/大小搜索聊天
- `telegram-search-global` — 跨公共聊天和频道的全文搜索
- `telegram-search-messages` — 在聊天中全文搜索
- `telegram-get-unread` — 带主题详细信息的未读聊天
**聊天和成员信息**
- `telegram-get-chat-info` — 聊天详细信息和元数据
- `telegram-get-chat-members` — 群组/频道成员
- `telegram-get-chat-folders` — 用户的聊天文件夹
- `telegram-list-topics` — 带未读计数的文件讨论主题
- `telegram-read-topic-messages` — 读取讨论主题中的消息
- `telegram-get-invite-links` — 聊天邀请链接
- `telegram-get-reactions` — 带用户详细信息的消息反应
**个人资料和联系人**
- `telegram-get-profile` — 详细的个人资料（简介，照片，最后一次上线，付费）
- `telegram-get-profile-photo` — 下载个人资料照片
- `telegram-get-contacts` — 联系人列表
- `telegram-get-contact-requests` — 收到的非联系人消息
**贴纸**
- `telegram-get-sticker-set`
- `telegram-search-sticker-sets`
- `telegram-get-installed-stickers`
- `telegram-get-recent-stickers`
**媒体**
- `telegram-download-media` — 下载照片和文档
**安全状态变更**
- `telegram-mark-as-read` — 将聊天标记为已读
- `telegram-mute-chat` — 静音通知
**账户信息**
- `telegram-get-sessions` — 列出活动 Telegram 会话
有关完整的上游工具目录（包括 `send-message`，`forward-message`，群组管理员，个人资料写入等），请使用 CLI [`@overpod/mcp-telegram`](https://github.com/mcp-telegram/mcp-telegram)。
## 架构
- **传输**: Streamable HTTP (`/mcp`)
- **认证**: OAuth 2.0 (RFC 8414 + 7591 + 7636/PKCE S256)
- **登录**: 通过 MTProto 的二维码，嵌入在 OAuth 授权页面中
- **存储**: SQLite（会话，OAuth 令牌，使用日志）
- **Telegram 客户端**: [`@overpod/mcp-telegram`](https://github.com/mcp-telegram/mcp-telegram) 通过主/客户端 IPC —— 每个用户都在隔离的工作线程中运行
- **页面**: Hono JSX（登录，OAuth 授权，隐私，条款）
- **可观察性**: 结构化日志记录到 OTLP HTTP（SigNoz，Grafana Cloud 等），如果 `SIGNOZ_ENDPOINT` 为空到 stderr
- **部署**: Docker。生产环境使用 Docker Swarm + Traefik。
有关组件映射，请求生命周期和存储布局，请参阅 [`docs/architecture.md`](./docs/architecture.md)。
## 配置
所有运行时配置都是环境变量。必填TELEGRAM_API_ID`，`TELEGRAM_API，`ISSUER`。建议使用 `ADMIN_TOKEN` —— 没有它，`/api/*` 上的管理员操作（统计信息，操作员端会话导入）将返回 401。
完整的参考资料，包括必填和可选标志以及变更影响警告：[`docs/configuration.md`](./docs/configuration.md)。
## 开发
```bash
pnpm install
cp .env.example .env
pnpm dev # tsx 监视
pnpm test # 单元测试（node:test）
pnpm typecheck # tsc --noEmit
pnpm lint # biome
pnpm build # tsc → dist/
```
预提交钩子（`husky` + `biome check --staged`）在暂存文件上运行 Biome，并在安装了 Gitleaks 的情况下运行 `gitleaks protect --staged`（`brew install gitleaks`）。与 TruffleHog 相同的扫描在 CI 中每个 PR 上运行。
## 贡献
欢迎提交 PR。请先阅读 [`CONTRIBUTING.md`](./CONTRIBUTING.md) —— 它涵盖了云与上游范围的划分，开发设置和“不会合并”的列表。通过贡献，您同意 [行为准则](./CODE_OF_CONDUCT.md)。有关计划内容，已延期内容和明确超出范围的内容，请参阅 [`ROADMAP.md`](./ROADMAP.md)。
工具级功能（新的 `telegram-*` MCP 工具，MTProto 覆盖）属于上游 [`mcp-telegram`](https://github.com/mcp-telegram/mcp-仓库。本仓库处理托管问题：OAuth，多用户会话存储，速率限制，登录页面，运维。
## 维护
由 **一人** 在业余时间维护。对问题和 PR响应时间：~2-3 天。没有 SLA，没有层 —— 但托管服务是尽力保持正常运行。
状态更新通过 [@mcp_telegram_cloud_bot](https://t.me/mcp_telegram_cloud_bot 机器人发布 `/start` 订阅）。
## 安全
漏洞披露参阅 [`SECURITY.md`](./SECURITY.md请勿** 为安全问题公开问题。
## 许可证
[MIT](./LICENSE) ©, 2025-。
MCP 市场