内容
<p align="center">
<img src="assets/banner.svg" alt="Telegram MCP for Claude" width="100%">
</p>
<h1 align="center">Telegram MCP for Claude</h1>
<p align="center">
一个独立的 <a href="https://modelcontextprotocol.io">MCP</a> 服务器，为 Claude 提供了一整套 <b>Telegram</b> 工具 —<br>
这样它就可以在专用的 Telegram 群组中读取、发布、编辑、置顶、反应和分享文件。
</p>
<p align="center">
<img src="https://img.shields.io/badge/License-MIT-22c55e.svg" alt="MIT License">
<img src="https://img.shields.io/badge/python-3.10%2B-3776AB.svg" alt="Python 3.10+">
<img src="https://img.shields.io/badge/MCP-server-8b5cf6.svg" alt="MCP server">
<img src="https://img.shields.io/badge/Telegram-Bot%20API-38bdf8.svg" alt="Telegram Bot API">
<img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs welcome">
</p>
---
## ✨ 为什么
有时你希望 Claude **在群里** —— 不仅仅是一对一地回答你，而是
参与一个共享聊天，你（可能还有其他代理）协调工作。
该服务器使 Claude 成为一个**专用 Telegram 群组**的一流成员：
它读取对话，发布更新，置顶当天的决定，对
消息做出反应，并通过官方 **Telegram Bot API** 分享缩略图或文件。因为它是 Bot API（不是你的用户帐户），所以 bot **只会看到
它被添加到的群组** —— 永远不会是你的私人聊天。
## 🚀 功能
- 💬 **读取和发布** — 拉取最近的消息，发送文本（Markdown/HTML，回复，静默）。
- 🖼️ **分享媒体** — 通过本地路径、URL 或 `file_id` 发送照片和文档。
- ✏️ **管理消息** — 编辑、删除、转发。
- 📌 **置顶 / 取消置顶** — 将当前的决定或主题置顶。
- 👍 **反应** — 用表情符号确认。
- 🔒 **安全设计** — Bot API 范围仅限；环境变量存储密钥；`.env` 被 git 忽略。
- 🪶 **轻量级** — 一个文件，两个依赖，标准输入输出传输。
## 🧭 架构
```mermaid
flowchart LR
U["👤 你"]
H["🤖 其他代理<br/>(可选)"]
C["🧠 Claude"]
subgraph MCP["此服务器"]
T1["telegram MCP 工具"]
end
B(["Telegram Bot API"])
G[("📣 '运维' 群组")]
U --- G
H -- 其自身的 bot --> B
C --> T1 --> B
B <--> G
```
> 提示：如果另一个代理也轮询 Telegram，请给 **Claude 它自己的 bot** 在同一个
> 群组（每个 bot 一个 `getUpdates` 轮询器 - 见 [注意事项](#-notes--limits))。
## 🔄 实际操作
```mermaid
sequenceDiagram
participant U as 👤 你
participant G as 📣 群组
participant C as 🧠 Claude (MCP)
U->>G: "Ship the Fable 5 short?"
C->>G: read_messages
C->>G: send_message "开始了 — 正在草拟……"
C->>G: send_photo thumbnail.png
U->>G: 👍
C->>G: set_reaction ✅ + pin_message
```
## 🧰 工具（12）
| 工具 | 功能 |
|---|---|
| `get_me` | 验证令牌，显示 bot 身份 |
| `get_chat` | 群组信息（标题，类型，成员数量） |
| `read_messages` | 群组中的最近消息 |
| `send_message` | 发布文本（解析模式，回复，静默，无预览） |
| `send_photo` | 发送照片（本地路径 / URL / file_id） |
| `send_document` | 发送文件（本地路径 / URL / file_id） |
| `edit_message` | 编辑 bot 自己的消息 |
| `delete_message` | 删除消息（管理员；<48h） |
| `forward_message` | 从另一个聊天转发消息 |
| `pin_message` / `unpin_message` | 置顶 / 取消置顶 |
| `set_reaction` | 用表情符号反应（空 = 清除） |
`parse_mode` 接受 `Markdown`、`MarkdownV2` 或 `HTML`。
## ⚡ 快速开始
**1. 创建一个 bot** — 消息 [@BotFather](https://t.me/BotFather) → `/newbot` → 复制 **令牌**。
**2. 禁用隐私模式** 以便 bot 可以看到所有群组消息：
`@BotFather` → `/setprivacy` → 选择你的 bot → **禁用**。
**3. 创建一个群组** 并添加你的 bot（以及其他成员）。
**4. 查找群组 `chat_id`** — 发布消息，然后：
```bash
curl "https://api.telegram.org/bot<TOKEN>/getUpdates"
```
读取 `result[].message.chat.id`（群组为负数，例如 `-1001234567890`）。
**5. 安装并运行**
```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
TELEGRAM_BOT_TOKEN=... TELEGRAM_CHAT_ID=... python3 server.py # stdio MCP
```
## 🔌 连接到 Claude
将以下内容添加到你的 MCP 客户端配置（例如 Claude Desktop `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"telegram": {
"command": "/ABSOLUTE/PATH/.venv/bin/python3",
"args": ["/ABSOLUTE/PATH/server.py"],
"env": {
"TELEGRAM_BOT_TOKEN": "123456:ABC...",
"TELEGRAM_CHAT_ID": "-1001234567890"
}
}
}
}
```
重启客户端 → `telegram` 工具出现。试试：*"查看 Telegram 群组并总结我错过的部分。"*
## 💡 示例提示
- "发布到群组：构建完成，下一个消息中的审查链接。"
- "读取最近 30 条消息并告诉我需要我做出决定的内容。"
- "将 `~/YouTube/ep/thumb.png` 处的缩略图发送到群组，并附上说明。"
- "置顶关于今天主题的消息，并对我的上一个消息做出 ✅ 反应."
## 📝 注意事项和限制
- `read_messages` 使用 `getUpdates`：Telegram 保留更新时间约 24 小时，仅限 bot 所在的聊天，并且每个 bot **仅允许一个 `getUpdates` 轮询器**（webhook 或第二个轮询器 → HTTP 409）。多个代理 → 给每个代理 **其自己的 bot**。
- bot 无法看到 bot **加入群组前**发送的消息。
- `pin`/`delete` 需要 bot 是群组 **管理员**。
## 🔐 安全
- 永远不要提交你的真实 `.env` — 令牌存储在那里（`.gitignore` 排除它）。
- Bot API 范围仅限：**无访问权限到你的个人 Telegram 账户**。
## 🗺️ 路线图想法
- 内联键盘 / 按钮用于审批
- Webhook 模式（多消费者友好）
- 消息搜索和线程摘要
## 🤝 贡献
问题和 PR 欢迎。保持小巧，依赖轻量，Bot-API 范围限定。
## 📄 许可证
[MIT](LICENSE) © 2026 Yurii Kostiuk
