一个非官方、自托管、适用于 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: anymail-mcp
网关的只读操作：
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 形式返回，而不会暴露服务器的文件系统路径。
浏览器设置流程免去了在托管终端中执行 OAuth 命令的麻烦：
打开 https://YOUR_HOST/setup。
输入由 npm run generate-secrets 生成的私有 OWNER_CODE。
点击开始授权邮箱。
完成一次性的 Tencent 授权页面。
返回设置标签页，等待邮箱已连接。
凭证与 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 保存在密码管理器中，并仅在主机密钥管理器中保存其哈希值，以及用于独立签名的秘密。
端点 | 用途 | 身份认证方式 |
| 最小存活检查 | 无 |
| 私有 Tencent 邮箱浏览器设置 | 所有者会话 |
| MCP 连接器 OAuth（带 DCR） | OAuth 协议 |
| 连接器的所有者批准 | 所有者代码 + 限流 |
| 无状态双工具网关 | Bearer token |
本项目以 MIT License 开源发布。
本项目不包含 Tencent 的 Agent Mail CLI。Docker 构建流程将独立发布包@tencent-qqmail/agently-cli仅在构建时安装。该包单独依据 Apache-2.0 许可证分发。在生产环境中使用之前，请阅读其许可以及适用的条款。
This server cannot be deployed
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
Your agent needs a mailbox of its own — to receive, thread, draft and send, with attachments, without borrowing your personal inbox or your company's SMTP. **What you can ask for** • "Create an inbox for this agent and tell me its address." • "Read the new messages in this thread and draft a reply." • "Send this message with the attachment and wait for the response." • "Search this inbox for everything from that domain." • "Show delivery metrics and the events on this inbox." **How to use it** Point any MCP client at https://mcp.aisa.one/mail/mcp and sign in with OAuth — there is no key to create or paste. 49 tools: create and delete inboxes, list and read messages, raw message bodies, attachments, threads, drafts and draft attachments, send and reply, message search, inbox events, metrics, and list entries — reads and writes. **Why this rather than the source** A real inbox an agent owns, rather than an SMTP credential it borrows from a human. **It is also a door to the rest** The same login reaches 26 sources and 580+ operations. Find the contact elsewhere in the catalogue, then write to them from here — without adding a second server. **What it costs** Finding and inspecting an operation is free. Running one is billed per call at API prices, with no seat and no monthly minimum, and every call takes max_price_usd so an agent cannot overspend by accident. **Where else it reaches** https://mcp.aisa.one/sales/mcp finds the person to write to.
Email for AI agents: send, receive with a safety verdict, reply and approve, as MCP tools.
