内容
# Telegram MCP 服务器
本地的 [模型上下文协议](https://modelcontextprotocol.io) 服务器，为 AI 代理（如 Claude Code、Claude Desktop 或任何 MCP 客户端）提供受控访问**您自己的 Telegram 账户**：列出聊天记录、读取历史记录、搜索和发送消息，通过 Telegram 的 MTProto API。
使用 Python + [Telethon](https://docs.telethon.dev) 构建。完全在您的机器上运行；您的登录会话永远不会离开它。
  
## 为什么
Telegram 的 **Bot API 无法看到您现有的聊天记录** — 机器人是一种独立的身份，只能接收明确发送给它的消息。要让代理与**您的实际对话**合作，您需要 **MTProto 客户端 API**，并通过您的用户账户进行身份验证。该项目将此功能封装在一个小型、专注的 MCP 服务器中，以便任何支持 MCP 的代理都可以读取和操作您的 Telegram 消息，而无需您每次都编写粘合代码。
## 功能
- **6 种工具**，涵盖常见的读取和写入操作（见下文）
- **仅限本地** — 凭证和会话存储在 git 忽略的 `.env` 文件中；除 Telegram 外，任何内容都不会被发送到其他地方
- **标准 MCP stdio 服务器** — 与 Claude Code、Claude Desktop 或任何 MCP 客户端配合使用
- **一次性登录** — 交互式脚本存储可重用的会话字符串；无需每次运行都重新进行身份验证
- **小且可读** — 约 150 行 Python 代码，易于审核和扩展
## 工具列表
| 工具 | 描述 |
|------|-------------|
| `get_me()` | 返回连接的账户（健康检查） |
| `list_chats(limit=20)` | 您最近的对话 |
| `get_history(chat, limit=30)` | 来自一个聊天的最近消息 |
| `search_messages(chat, query, limit=30)` | 在一个聊天中搜索 |
| `search_all(query, limit=30)` | 在**所有**聊天中搜索 |
| `send_message(chat, text)` | 以您的身份发送消息 |
`chat` 参数接受用户名（`@name`）、数字 ID、电话号码、`t.me` 链接或聊天的显示名称。
## 快速开始
### 1. 安装
```bash
git clone https://github.com/<you>/telegram-mcp.git
cd telegram-mcp
python -m venv .venv
# Windows
.venv\Scripts\pip install -r requirements.txt
# macOS / Linux
.venv/bin/pip install -r requirements.txt
```
### 2. 获取 API 凭证
前往 [my.telegram.org](https://my.telegram.org) → **API 开发工具** → 创建一个应用 → 复制 `api_id` 和 `api_hash`。
### 3. 登录（一次性）
```bash
# Windows
.venv\Scripts\python login.py
# macOS / Linux
.venv/bin/python login.py
```
输入您的 `api_id`/`api_hash`、电话号码（带国家代码）和 Telegram 发送的登录代码（以及您的 2FA 密码，如果已设置）。这会将可重用的会话字符串写入 `.env`。
### 4. 在您的 MCP 客户端上注册
**Claude Code:**
```bash
claude mcp add telegram --scope user -- "/abs/path/.venv/bin/python" "/abs/path/server.py"
```
**Claude Desktop** — 添加到 `claude_desktop_config.json`:
```json
{
"mcpServers": {
"telegram": {
"command": "/abs/path/.venv/bin/python",
"args": ["/abs/path/server.py"]
}
}
}
```
重启您的客户端，`telegram` 工具即可使用。
## 示例
> **您：** 在我的所有 Telegram 聊天记录中搜索“invoice”，并总结未完成的事项。
代理调用 `search_all("invoice")`，返回：
```json
[
{
"id": 84213,
"date": "2026-07-02T09:14:00+00:00",
"chat": "Acme Billing",
"from": "Acme Billing",
"text": "Invoice #204 is due on the 10th."
}
]
```
……然后代理从此处开始总结。
## 工作原理
`login.py` 通过 Telethon 进行一次身份验证，并将 `StringSession` 保存到 `.env`。`server.py` 构建一个 [FastMCP](https://modelcontextprotocol.io) stdio 服务器，在第一次工具调用时延迟连接，验证会话已授权，并将每个工具映射到 Telethon 调用（`iter_dialogs`、`iter_messages`、`SearchGlobalRequest`、`send_message`）。结果作为纯 JSON 可序列化字典返回。
## 安全
- **请保持 `.env` 私有。** `SESSION_STRING` 等同于以您的身份登录。请勿将其提交到 git 中。
- 所有操作都在本地运行；服务器仅与 Telegram 服务器通信。
- 自动使用**用户账户**是 Telegram 服务条款的灰色地带。读取您自己的账户通常是可以的；请保持发送消息的频率为人类级别，避免批量/垃圾邮件活动，以避免账户限制。
## 限制
- 暂无自动测试套件 — 已手动验证通过实时账户。
- `search_messages` 在单个聊天中搜索；使用 `search_all` 进行全局搜索。
- 显示名称解析会回退到扫描您的对话列表，因此确切的用户名/ID 更快、更可靠。
## 许可证
[MIT](LICENSE)
