内容
---
title: Telegram MCP（个人，只读）
emoji: 📬
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: false
license: apache-2.0
short_description: 个人 Telegram MCP，只读，Bearer 认证
---
# Telegram MCP — 个人远程桥
一个自我托管的桥，将 [chigwell/telegram-mcp](https://github.com/chigwell/telegram-mcp)（基于 Telethon）作为远程 MCP 服务器通过可流式传输的 HTTP 公开。
- **用户机器人** — 通过 MTProto（Telethon）在您的个人 Telegram 账户下运行，不需要机器人，不需要添加聊天。
- **只读** — `TELEGRAM_EXPOSED_TOOLS=read-only`。仅公开约 30 个只读工具（列出聊天、读取消息、搜索、下载媒体等）。发送/编辑/删除/群组管理员工具未注册。
- **Bearer 令牌保护** — Caddy 在流式 HTTP 服务器前面拒绝所有没有 `Authorization: Bearer <MCP_BEARER_TOKEN>` 的请求。
## 端点
`https://francescomiliani-telegram-mcp.hf.space/mcp`（可流式传输的 HTTP，MCP 规范 2025-03-26）。
## 所需空间密钥
在空间的 **设置 → 变量和密钥** 中配置这些：
| 名称 | 值 | 获取位置 |
|---|---|---|
| `TELEGRAM_API_ID` | int | https://my.telegram.org/apps |
| `TELEGRAM_API_HASH` | string | https://my.telegram.org/apps |
| `TELEGRAM_SESSION_STRING` | 长 base64 字符串 | 使用 chigwell/telegram-mcp 中的 `uv run session_string_generator.py --qr` 在本地生成 |
| `MCP_BEARER_TOKEN` | 长随机字符串 | `openssl rand -hex 32` |
`TELEGRAM_EXPOSED_TOOLS=read-only` 被设置为默认空间变量（非密钥）。
## 从 MCP 客户端连接
```bash
# Claude 代码
claude mcp add --transport http telegram \
https://francescomiliani-telegram-mcp.hf.space/mcp \
--header "Authorization: Bearer $MCP_BEARER_TOKEN"
# Codex
codex mcp add telegram \
--url https://francescomiliani-telegram-mcp.hf.space/mcp \
--header "Authorization: Bearer $MCP_BEARER_TOKEN"
```
对于仅限 stdio 的客户端（Claude Desktop，一些 Windsurf 版本），通过 `mcp-remote` 进行桥接：
```json
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://francescomiliani-telegram-mcp.hf.space/mcp",
"--header", "Authorization: Bearer ${MCP_BEARER_TOKEN}"],
"env": { "MCP_BEARER_TOKEN": "<your-token>" }
}
}
}
```
## 安全性
- 空间 URL 是公开的。Bearer 令牌是公共互联网和您的 Telegram 账户之间的唯一保障。
- 将 `TELEGRAM_SESSION_STRING` 当作密码 — 任何拥有它的人都可以读取/写入您的账户。
- 免费的 HF 空间在 48 小时不活动后进入睡眠模式。会话被保留（字符串会话模式），因此下一个请求只需唤醒容器并重新连接。预计有 20–40 秒的冷启动时间。
## 架构
```
互联网 ──HTTPS──▶ Caddy :7860 ──（Bearer 检查）──▶ main.py :8765 ──（Telethon/MTProto）──▶ Telegram
│ │
└─ 401 如果没有/错误的 Bearer └─ 流式 HTTP MCP，/mcp 端点
```
