内容
# Telegram 安全 MCP 服务器
适用于 Telegram 的终极模型上下文协议（MCP）服务器，专为 AI 代理（如 Claude、Gemini 等）提供安全、实时和多模态访问您的 Telegram 账户而设计。
与其他 Telegram MCP 实现不同，该项目重点关注 **隐私、跨平台稳定性、多模态原生支持和性能**。
## 为什么选择我们？（杀手级功能）
1. **原生多模态音频和视频解析**：
AI 代理传统上难以处理原始 `.ogg` 语音消息或 Telegram 专有视频笔记。我们的服务器使用捆绑的 `ffmpeg` 二进制文件（通过 `imageio-ffmpeg`）拦截并即时将音频文件打包成标准 `.mp4` 容器。这允许高级多模态神经网络原生地“听”和“看”文件，而无需依赖不稳定的第三方 API（如 Google Speech Recognition）。它完全是跨平台的！
2. **AES-256 内存加密**：
您的 Telegram API 密钥和会话字符串极为敏感。大多数 MCP 将它们留作纯文本 `.env` 文件。我们构建了一个交互式 `encrypt_setup.py`，该程序使用 PBKDF2 从 4 位 PIN 推导出 AES-256 密钥。您的会话在运行时被解密到内存中 - 绝不将纯文本密钥写入磁盘！
3. **草稿支持和安全边界**：
AI 代理可以通过 `save_draft` 工具安全地撰写回复。您可以在手动发送之前在 Telegram 应用中查看草稿。此外，该 MCP 被硬编码为完全阻止访问私人消息（DM）和机器人。仅允许访问群组和超级群组聊天，提供了一个无缝的安全边界。
4. **雷达模式（实时等待）**：
再也不需要 API 轮询循环。我们的服务器使用 `asyncio.Event` 暂停 AI 的执行线程，并在指定聊天中新消息到达的毫秒级立即唤醒它。
5. **超快速 SQLite 缓存**：
我们在后台进程中本地解析传入的消息，确保 AI 可以立即在本地 SQLite 数据库中搜索上下文，而无需不断地调用 Telegram API。
---
## 先决条件
- Python 3.9+
- macOS、Linux 或 Windows
- Telegram API ID 和 Hash（可在 [my.telegram.org](https://my.telegram.org) 获取）
*(注意：对于没有桌面环境的 Linux 用户，PIN 输入系统使用 `tkinter`。如果您在无头服务器上运行，请确保安装了 `python3-tk` 并转发了 X11/Wayland 显示，或者修改代码以使用标准 `input()`)*
## 安装（跨平台）
1. 克隆此存储库。
2. 安装所需的依赖项：
```bash
pip install -r requirements.txt
```
3. 将 `.env.example` 复制到 `.env` 并填写您的 Telegram API 凭证：
```env
TELEGRAM_API_ID=12345678
TELEGRAM_API_HASH=your_api_hash_here
TELEGRAM_SESSION_NAME=master_account
```
4. 运行安全设置脚本以认证和加密您的会话：
```bash
python encrypt_setup.py
```
系统将要求您通过手机号码和验证码登录 Telegram。成功登录后，本地 GUI 提示将要求您创建 **4 位 PIN**。您的会话将被加密到 `config.enc`，并且您将被提示安全删除 `.env` 和 `.session` 文件。
## 运行服务器
您可以通过将环境中的 Python 可执行文件指向 `main.py` 来将此服务器插入您首选的 MCP 客户端（例如 Claude Desktop、Cursor 或 Antigravity IDE）：
```json
{
"mcpServers": {
"TelegramMCP": {
"command": "/path/to/your/venv/bin/python",
"args": ["/path/to/Telegram-MCP-Release/main.py"]
}
}
}
```
启动 MCP 服务器后，将出现一个小窗口，请求您的 4 位 PIN。输入后，服务器开始为您的 AI 提供工具！
## 可用工具
- `list_my_chats`：列出 AI 可用的所有群组聊天。
- `find_my_chat`：搜索特定的群组聊天。
- `search_in_my_chats`：跨超快速本地 SQLite 缓存和 Telegram 云的全局关键词搜索。
- `get_chat_messages`：获取消息历史记录。
- `get_chat_messages_around`：获取特定消息上方和下方的内容。
- `get_chat_messages_after`：顺序获取特定消息之后的消息。
- `search_global_public_chats`：查找公共 Telegram 群组。
- `get_chat_info`：关于聊天的详细信息。
- `download_message_media`：下载照片、文档，并智能地将 `.ogg` 语音笔记转换为 `.mp4` 以供 AI 直接使用。
- `send_message`：向允许的聊天发送消息。
- `save_draft`：保存已撰写的消息作为草稿供人工审核。
- `wait_for_new_messages`：暂停 AI 直到新消息到达（雷达模式）。
