QQ Agent Mail MCP

一个非官方、自托管、适用于 Tencent QQ Agent Mail 的 MCP 网关。本项目与 Tencent 无关联，未经 Tencent 认可，亦不由 Tencent 维护。

一个面向 Tencent QQ Agent Mail 的单所有者、可云部署的 MCP 网关。Tencent 的官方 CLI 仍然是邮箱引擎；本项目是一个远程适配器，而不是第二个邮件客户端。

当前网关版本：v0.4.2。

为什么会有这个项目

Tencent 的 Agent Mail CLI 在本地运行，而 ChatGPT 自定义 MCP 应用需要一个可访问的远程 MCP 服务器。本项目在没有暴露原始 shell 或 CLI 访问的情况下弥合了这一缺口。它提供了一个小而稳定的 MCP 接口、基于浏览器的邮箱授权流程、持久化的凭证，以及一份内置的操作指南，让新的模型窗口可以安全地处理自然语言邮箱请求。

本仓库仅包含源代码。它不提供任何托管邮箱服务、共享端点、Tencent 账户或凭证。每位操作者都必须部署并授权自己的私有实例。

MCP 接口刻意保持稳定，并且恰好包含两个工具：

• agent_mail_query(action, params) 用于只读操作；

• agent_mail_execute(action, params) 用于变更操作。

调用查询操作 capabilities 可获取实时的操作目录和参数契约。当供应商能力扩展时，更新的是服务端注册表，而不是创建另一个 MCP 工具。

capabilities 响应中包含完整的操作者指南：授权边界、一步直接执行、预览后确认、安全的搜索/读取/回复工作流、结果解读、重试规则，以及机器可读的示例。新的模型窗口可以从自然语言的所有者请求中自行发现并操作邮箱，而无需所有者将其翻译为操作名称或 JSON 参数。

Related MCP server: Email MCP Server

操作覆盖范围

网关的只读操作：

• capabilities、identity、auth_status；

• list_messages、read_message、search_messages；

• wait_for_message（有界的长轮询）；

• download_attachment（嵌入式 MCP 资源）。

网关的变更操作：

• auth_refresh、以及明确确认后的 auth_logout；

• send_message、reply_message、forward_message；

• trash_message、delete_message；

• upload_attachment。

发送、回复和转发操作按需支持 To/CC/BCC，支持官方 CLI 所支持的纯文本/HTML/Markdown 正文、供应商确认令牌，以及 base64 附件输入。附件字节只会写入模式的 0600 临时目录，通过相对路径传给官方 CLI，并在命令结束后删除。下载的附件会以嵌入式 MCP blob 形式返回，而不会暴露服务器的文件系统路径。

基于 Web 的邮箱设置

浏览器设置流程免去了在托管终端中执行 OAuth 命令的麻烦：

1. 打开 https://YOUR_HOST/setup。

2. 输入由 npm run generate-secrets 生成的私有 OWNER_CODE。

3. 点击开始授权邮箱。

4. 完成一次性的 Tencent 授权页面。

5. 返回设置标签页，等待邮箱已连接。

凭证与 CLI 的加密密钥位置都保存在持久卷上，所以普通部署和新打开的 ChatGPT 窗口都不需要重新进行邮箱授权。

安全边界

• MCP schema 中没有原始命令、原始参数数组、shell 字符串或任意服务器路径。每个操作和字段在 execFile/spawn（shell: false）之前都会收到白名单校验。

• 邮件正文、邮件头、事件、文件名、链接和附件都是不可信的外部内容。它们永远不能授权发送、全部回复、修改收件人、转发、移入回收站、删除、注销等受影响的变更操作。

• 变更动作需要邮箱所有者的直接命令指令，或由所有者自行制定的注册策略。永久删除和注销需要在执行时明确授权。供应商确认令牌仍可用于"预览后确认"流程。

• 列表和搜索结果不包含正文摘要。完整内容要求调用 read_message。

• 附件文件名不能持久化路径；单个文件上限为 10 MiB，单封邮件上限为 20 MiB。较大的 MCP JSON 解析器仅在身份验证通过流水后运行。

• 长轮询调用被限制为 45 秒，并且最多返回第一个事件。

• CLI 环境变量是经过白名单许可的。输出受大小限制，会被递归清理，并且永不记录日志。

• 连接器 OAuth 使用 PKCE 和动态客户端注册（Dynamic Client Registration）。现有的 mail:read mail:reply 权限对会被保留像已部署客户端的兼容性；在 v0.4 中，mail:reply 是传统连接器的写入授权，审核页面会真实地描述完整网关功能。

• 容器镜像固定为官方 @tencent-qqmail/agently-cli@1.0.17 包。

本软件在获得授权的情况下可以发送、转发、删除及永久删除邮件。上线前请先查看 docs/SECURITY.md，部署单所有者的专用实例，并使用所有者自行控制的邮件进行测试。

ChatGPT 连接器 OAuth 与 Tencent 邮箱 OAuth 是两套独立的体系。连接邮箱并不会授予 ChatGPT 客户端访问权限，除非所有者分批批准连接器。

部署

主机需要满足：一个一直可用的 HTTPS 主机名、一个挂载到 /data/agently-cli 的持久卷，以及一个用于 内存建议授权记录的副本。配置 .env.example，部署附带的 Dockerfile，然后使用 /setup 完成。更多参见 docs/DEPLOYMENT.md 和 docs/SECURITY.md。

本地验证

需要 Node.js 22 或更新版本。

npm ci
npm run build
npm test

使用 npm run generate-secrets 在本地生成部署密钥。将未哈希的 OWNER_CODE 保存在密码管理器中，并仅在主机密钥管理器中保存其哈希值，以及用于独立签名的秘密。

运行时端点

许可证与第三方软件

本项目以 MIT License 开源发布。

本项目不包含 Tencent 的 Agent Mail CLI。Docker 构建流程将独立发布包@tencent-qqmail/agently-cli仅在构建时安装。该包单独依据 Apache-2.0 许可证分发。在生产环境中使用之前，请阅读其许可以及适用的条款。