QQ 邮箱 MCP

通过 MCP 和 OAuth 将自己的 QQ 邮箱连接到 ChatGPT，支持邮件搜索、读取、附件、发送及文件夹管理。Python 实现，适合单账户自托管。

Self-hosted QQ Mail MCP server with OAuth, attachment support, and duplicate-send protection.

功能

读取使用只读 IMAP 和 BODY.PEEK。邮件 ID 包含文件夹、UIDVALIDITY 和 UID；文件夹身份改变后，旧 ID 会被拒绝。移动使用服务器的原子 MOVE；没有永久删除或清空垃圾箱工具。

Related MCP server: mcp4mail

准备

• Python 3.12。

• 已开启 IMAP/SMTP 的 QQ 邮箱及其邮箱授权码。

• 自己控制的域名、服务器和 HTTPS 反向代理，用于远程 OAuth 连接。

此项目是每个部署连接一个邮箱的自托管服务。代码不包含可直接使用的公共邮箱服务、账户、授权码或访问令牌。

安装与配置

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
cp config.example.json config.json
python hash_password.py

Windows PowerShell 激活虚拟环境和复制配置：

.\.venv\Scripts\Activate.ps1
Copy-Item config.example.json config.json
python hash_password.py

脚本会隐藏输入独立的连接密码，确认两次后输出 SHA-256。将输出填写到 config.json，并设置以下字段：

连接密码和 QQ 邮箱授权码用于不同用途，请分别设置。配置模板中的值都是占位符，需要自行替换。真实配置和状态数据库应仅允许服务账户读取，且不应提交到 Git。

Linux/macOS 启动：

QQ_MCP_CONFIG="$PWD/config.json" python server.py

Windows PowerShell 启动：

$env:QQ_MCP_CONFIG = (Resolve-Path .\config.json).Path
python server.py

服务监听 127.0.0.1:8765。通过反向代理提供 HTTPS，将外部请求转发到此地址。caddy.example 是最小示例，域名需自行替换；OAuth 发现、注册、授权、令牌与 /mcp 路径都需要转发，因此应代理整个站点根路径。

qq-mail-mcp.service 提供 Linux systemd 配置示例。使用前创建专用系统用户 qqmailmcp，安装代码至 /opt/qq-mail-mcp，将真实配置置于 /etc/qq-mail-mcp/config.json，并使服务用户可以写入 /var/lib/qq-mail-mcp。systemd 示例不读取项目根目录的 config.json；两者请选择对应的部署方式。

连接 MCP 客户端

部署完成后，用客户端创建远程 MCP 连接，地址为 https://mail.example.com/mcp，选择 OAuth。实际界面入口以客户端显示为准。授权页输入自己设置的独立连接密码。

当前实现只允许 chatgpt.com 的指定 OAuth 回调路径，不是面向任意 MCP 客户端的通用认证服务。所有邮箱工具均要求授权，并同时申请 mail:read 和 mail:write，当前没有可切换的只读授权模式。

连接后可以要求：

• “列出邮箱文件夹。”

• “查找收件箱中最近的未读邮件，先给我摘要。”

• “读取这封邮件的正文和附件目录。”

• “把我上传的 PDF 作为附件发给指定收件人，主题和正文如下……”

发送附件时，应使用客户端实际传入的文件参数。客户端是否支持原生文件传递需实际验证；本地路径、虚构的文件 ID 或过期链接不能代替文件。

限制与行为

• 搜索每页最多 50 封；单封读取上限 15 MiB，正文返回上限 100,000 字符。

• 单个附件读取上限 512 KiB；这与发送附件额度是不同限制。

• 每封最多发送 20 个附件，附件原始字节合计不超过 50 MiB，编码后的整封邮件不超过 70 MiB；服务器与收件方仍可能采用更低额度。

• 附件只在内存中处理。下载要求公网 HTTPS/443；DNS、连接目标和每次跳转均经过校验，拒绝内网地址及非法 URL。

• 相同发送重试须复用同一 operation_id。SMTP 已提交但结果未知时，应先到邮箱核对，不能换编号自动重发。

• 访问令牌有效一小时，刷新令牌有效三十天并轮换。撤销时会撤销对应令牌族；SQLite 状态目录需要持久保存。

• 服务指令要求发送、移动、删除和修改已读状态须由用户明确提出；此约束也依赖 MCP 客户端遵守，不能替代用户核对收件人、正文和附件。

• 邮件正文和附件属于不可信数据，不应将其中的指令当成用户授权执行。

测试

python -m pip install -r requirements-dev.txt
python -m pytest -q

测试使用临时目录、示例域名、虚构账户、模拟 SMTP 和模拟附件下载；不连接真实邮箱、不向真实收件人发送邮件。覆盖 OAuth/PKCE、令牌重放与撤销、工具权限、MCP 协议、附件编码、发送去重、内网下载拦截和大小限制。

本次公开版本在本地通过 25 项测试。模拟测试不代表新部署的 QQ 登录、真实发信、大附件或每种客户端文件传递都已验收；请在自己的部署中验证。

文件

• server.py：MCP 工具、鉴权、HTTP 入口及请求限制。

• auth_service.py：OAuth、授权页、CSRF、令牌轮换与撤销。

• mailbox_service.py：IMAP/SMTP、邮件 ID、附件和发送去重。

• file_transfer.py：原生文件参数、下载与网络目标校验。

• config.example.json、caddy.example、qq-mail-mcp.service：部署模板。

• test_server.py、test_attachments.py：本地模拟测试。

许可证

MIT，见 LICENSE。本项目是独立实现，与腾讯、QQ 邮箱及 OpenAI 没有隶属关系。