QQmail plugin

面向 Codex 等 MCP 宿主的本地 Windows 邮箱插件。当前版本 0.3.0，提供 23 个工具，支持 QQ 邮箱、腾讯企业邮箱及用户配置的 IMAP/SMTP 服务。

功能

• 账户设置、连接测试、多账户档案与经确认的账户切换。

• 邮件搜索、分页读取、线程读取、标记、移动及移入垃圾箱。

• 草稿准备、查询、编辑、取消，以及加密保存和恢复。

• 发送、回复、回复全部、转发；支持由用户在原生窗口选择的本地附件。

• 附件下载、待发送附件查询和移除。

• 发送、移动和移入垃圾箱需要独立 Windows 确认；不提供永久删除。

Related MCP server: simple-email-mcp

安装和运行

需要 Windows 交互式桌面、Node.js 22 或以上版本、系统自带的 Windows PowerShell。需要使用邮箱服务商提供的 IMAP/SMTP 授权码。授权码只在本地设置页面输入。

仓库中的 QQmailplugin/ 是已构建的可运行包，依赖已打包，无需执行 npm install。也可从 Releases 下载运行包。

1. 将完整 QQmailplugin 文件夹放到本机固定位置。

2. 支持 Codex 插件的宿主使用其中的 .codex-plugin/plugin.json 和 .mcp.json；其他 MCP 宿主使用 stdio 配置：

   {
     "mcpServers": {
       "qq-mail": {
         "command": "node",
         "args": ["C:/Tools/QQmailplugin/dist/server.mjs"]
       }
     }
   }

   将示例路径替换为自己的实际路径，工作目录使用插件根目录。

3. 调用 get_account_status，再调用 open_settings。在设置页保存账户和授权码，按提示确认并测试连接。

4. 发送附件时先调用 select_attachments，再将返回的 attachmentId 传给 prepare_email，最后调用 send_email 并在原生窗口确认。

完整操作、限制与数据流见 运行说明。校验运行包：

python scripts/verify-runtime.py

安全边界

插件只暴露邮箱操作和账户设置，不提供任意命令、代码执行、宿主行为修改或任意文件路径上传接口。邮件和附件内容作为不可信数据处理。插件正常连接已确认配置的邮箱服务器；没有自建遥测或云端转发服务。

读取结果会返回 MCP 宿主，宿主可能将其发送给模型服务。普通安装不自动获得操作系统沙箱；插件也不能限制宿主已有的其他工具权限。详情见 SECURITY.md。

源码开发

仓库根目录包含 TypeScript 源码、设置页面源码和合成测试；QQmailplugin/ 单独保存可运行成品。

npm ci
npm run typecheck
npm test
npm run build

npm run build 生成根目录 dist/ 和 ui/settings.html，不会覆盖 QQmailplugin/。原生 Windows 测试需要 Windows；浏览器测试使用 Microsoft Edge，也可通过 QQMAIL_TEST_BROWSER 指定测试浏览器后执行 npm run test:ui。开发测试只能使用合成邮箱和测试配置，不要复用日常邮箱配置。完整插件和依赖应在单独的受限测试环境运行。

测试目录中的 TLS 证书和密钥为公开合成 fixture，不能用于生产。QQMAIL_APPCONTAINER_TEST 是原有受控测试基础设施的选择开关；该外部基础设施未随本仓库提供，普通开发环境无需启用。

0.3.0 的既有受控验收包括 246/246 项业务测试，以及浏览器、原生确认、附件选择、隔离和独立安装检查。公开仓库不包含原始系统元数据、个人运行记录或测试环境。验收范围和未测项见 验证说明。

来源和许可

改编自 moondream69/QQmail-plugin，基线提交 146923e。保留 MIT 许可证 及原作者版权声明。本仓库维护本地改编版本，不是腾讯官方产品。

依赖来源、版本及完整性见 SBOM，第三方许可见 THIRD_PARTY_NOTICES。