QQ 邮箱 MCP
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
QQ 邮箱 MCP
通过 MCP 和 OAuth 将自己的 QQ 邮箱连接到 ChatGPT,支持邮件搜索、读取、附件、发送及文件夹管理。Python 实现,适合单账户自托管。
Self-hosted QQ Mail MCP server with OAuth, attachment support, and duplicate-send protection.
功能
工具 | 用途 |
| 列出邮箱文件夹 |
| 按关键词、发件人、日期、未读状态搜索邮件 |
| 读取正文与附件目录,保留原有未读状态 |
| 读取小附件,文本直接返回,二进制返回 Base64 |
| 发送纯文本邮件及附件,通过 |
| 将邮件移动到已有文件夹 |
| 移入垃圾箱 |
| 按要求标记已读或未读 |
读取使用只读 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.pyWindows PowerShell 激活虚拟环境和复制配置:
.\.venv\Scripts\Activate.ps1
Copy-Item config.example.json config.json
python hash_password.py脚本会隐藏输入独立的连接密码,确认两次后输出 SHA-256。将输出填写到 config.json,并设置以下字段:
字段 | 内容 |
| 自己服务的 HTTPS 根地址,例如 |
| 可写的私有持久目录;本地可用 |
| 自己的完整 QQ 邮箱地址 |
| QQ 邮箱授权码,非 QQ 登录密码 |
| 独立连接密码的 SHA-256,小写十六进制字符串 |
连接密码和 QQ 邮箱授权码用于不同用途,请分别设置。配置模板中的值都是占位符,需要自行替换。真实配置和状态数据库应仅允许服务账户读取,且不应提交到 Git。
Linux/macOS 启动:
QQ_MCP_CONFIG="$PWD/config.json" python server.pyWindows 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 没有隶属关系。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Connect any IMAP/SMTP mailbox to Claude & ChatGPT: search, read, sort, draft. Sends only with OK.
Connect any mailbox to Claude, ChatGPT & AI: read, send, reply, schedule & search emails.
Your mailboxes in ChatGPT and Claude: Gmail, iCloud, Fastmail, any IMAP. Passwords stay yours.
Gmail, Outlook, iCloud, Fastmail and any IMAP mailbox for your agent. Scoped OAuth, approved sends.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceConnects MCP-compatible AI assistants to any IMAP/SMTP mailbox, enabling email search, reading, folder management, and sending with automatic saving to Sent.1MIT
- AlicenseNot gradedqualityBmaintenanceConnects an IMAP mailbox over OAuth 2.1 so an AI assistant can list and search accounts, folders, messages, attachments, and contacts. Mailboxes stay read-only by default, with optional opt-in write tools for flagging, moving, drafting, and approval-gated sending.MIT
- AlicenseNot gradedqualityBmaintenanceEnables Claude and ChatGPT to read, search, and organize mail in a user's own email account, including folders, threads, attachments, drafts, and optional sending, with per-user permission levels and OAuth-secured remote connections.MIT
- AlicenseAqualityBmaintenanceEnables AI apps to securely read, search, organize, draft, attach files to, and send email across up to five self-hosted IMAP/SMTP mailboxes, with sending only after explicit user approval.18AGPL 3.0