内容
# Agently Mail MCP Server
纯 Python 实现的腾讯 QQ 邮箱 MCP 服务。基于逆向分析 `@tencent-qqmail/agently-cli` v1.0.6 得到的 REST API 协议，**无需 Node.js / npm**。
---
## 概述
本服务是一个 **MCP (Model Context Protocol) Server**，使用 **Python FastMCP** 框架实现，通过 HTTP 直接调用腾讯 Agent REST API 完成邮件操作。
**核心特点：**
- 纯 Python，零 Node.js 依赖
- OAuth 2.0 Device Flow 认证（RFC 8628）
- Token 本地文件持久化（`~/.config/agently-mail/token.json`）
- 支持两阶段确认发送（防误操作）
- 自动刷新 access_token
---
## 前置条件
| 依赖 | 版本要求 | 说明 |
|------|---------|------|
| Python | >= 3.10 | |
| `mcp` | >= 1.28 | MCP SDK |
| `httpx` | >= 0.27 | HTTP 客户端 |
---
## 安装
```bash
cd H:\agentmail-qq-cli
# 安装 Python 依赖
python -m pip install mcp httpx
```
---
## 在 OpenCode 中配置
编辑 `~/.config/opencode/opencode.json`，添加：
```json
{
"mcp": {
"agently-mail": {
"type": "local",
"command": ["python", "H:\\agentmail-qq-cli\\agently_mcp_server.py"],
"enabled": true
}
}
}
```
重启 OpenCode 后即可使用。
---
## 首次使用：登录认证
在 AI 对话中调用 `auth_login` 工具：
```
auth_login()
```
按照提示在浏览器中完成授权，凭据将保存在 `~/.config/agently-mail/token.json` 中。
也可通过环境变量直接指定 token（跳过 OAuth）：
```
set AGENTLY_ACCESS_TOKEN=your_token_here
```
---
## 可用工具（14 个）
### 邮件操作
| 工具 | 描述 | 关键参数 |
|------|------|---------|
| `send_email` | 发送新邮件（两阶段确认） | `to[]`, `subject`, `body`, `cc[]`, `bcc[]`, `attachment_ids[]` |
| `list_messages` | 列出邮件 | `limit`, `folder`(inbox/sent/trash/spam), `cursor`, `is_unread` |
| `read_message` | 读取邮件完整内容 | `message_id` |
| `search_messages` | 搜索邮件 | `query`, `folder`, `limit`, `search_in` |
| `reply_message` | 回复邮件（两阶段确认） | `message_id`, `body`, `reply_all` |
| `forward_message` | 转发邮件（两阶段确认） | `message_id`, `to[]`, `body` |
| `trash_message` | 移至垃圾箱（两阶段确认） | `message_id` |
### 附件操作
| 工具 | 描述 | 关键参数 |
|------|------|---------|
| `upload_attachment` | 上传文件作为附件 | `file_path` |
| `download_attachment` | 下载附件到本地 | `message_id`, `attachment_id`, `output_dir` |
### 认证与账户
| 工具 | 描述 |
|------|------|
| `auth_login` | OAuth 设备流登录 |
| `auth_status` | 查看认证状态 |
| `auth_logout` | 登出清除凭据 |
| `auth_refresh` | 手动刷新访问令牌 |
| `get_user_info` | 获取用户信息与别名列表 |
---
## 使用示例
```
# 查看认证状态
auth_status()
# 查看当前邮箱信息
get_user_info()
# 收件箱列表
list_messages(limit=10, folder="inbox")
# 发送邮件（两阶段确认）
send_email(
to=["colleague@example.com"],
subject="季度报告",
body="请查收附件中的季度报告。",
attachment_ids=["file_xxx"]
)
# 首次返回 confirmation_token，带上它完成发送：
send_email(
to=["colleague@example.com"],
subject="季度报告",
body="请查收附件中的季度报告。",
attachment_ids=["file_xxx"],
confirmation_token="<上一步返回的token>"
)
# 搜索邮件
search_messages(query="会议", folder="inbox", limit=20)
```
---
## 协议说明
本服务**不**使用传统 SMTP/IMAP/POP3 协议，而是通过 **腾讯 Agent REST API** 实现邮件收发。
| 功能 | 传统协议 | 本服务使用的 API |
|------|---------|-----------------|
| 发信 | SMTP (25/465/587) | `POST /v1/aliases/{id}/messages/send` |
| 收信 | IMAP (143/993) / POP3 (110/995) | `GET /v1/aliases/{id}/messages` |
| 认证 | SMTP AUTH / SASL | OAuth 2.0 Device Flow |
| 附件 | MIME 编码 | REST multipart 上传/下载 |
| Token | 无 | Bearer JWT + refresh_token |
**API 端点：**
- Auth: `https://auth.agent.qq.com`
- REST: `https://api.agent.qq.com`
---
## 环境变量
| 变量 | 用途 |
|------|------|
| `AGENTLY_ACCESS_TOKEN` | 直接指定 access_token，跳过 OAuth 流程 |
| `AGENTLY_CLIENT_ID` | OAuth client_id（默认 `agently-cli`） |
| `AGENTLY_CLIENT_SECRET` | OAuth client_secret（可选） |
| `AGENTLY_CONFIG_DIR` | 配置文件目录（默认 `~/.config/agently-mail`） |
---
## 项目结构
```
H:\agentmail-qq-cli\
├── agently_mcp_server.py # MCP Server 主程序（纯 Python，~400行）
├── README.md # 本文件
└── LICENSE # MIT 许可证
```
**零 Node.js / npm 依赖。** 只有一个 Python 文件和一个 JSON token 文件。
---
## 许可证
MIT License
Copyright (c) 2026
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
