QQ Mail Reader MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@QQ Mail Reader MCP list my unread QQ Mail messages"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
QQ Mail Reader MCP
English | 简体中文
A read-only QQ Mail MCP server for ChatGPT and Codex. It supports both a local single-user mode and a multi-user HTTP mode with OAuth 2.1 and PKCE. Every mail operation uses a read-only QQ Mail IMAP connection.
Portfolio project: a security-first QQ Mail integration built with Node.js, Model Context Protocol, OAuth 2.1/PKCE, and IMAP.
Highlights
Least privilege by design: exposes only five tools for identity, connection status, unread messages, search, and message reading. It cannot send, delete, move, or mark mail as read.
Complete authorization flow: implements OAuth discovery, Dynamic Client Registration, Authorization Code with PKCE S256, token rotation, revocation, and UserInfo.
Credential protection: local mode uses macOS Keychain; HTTP mode encrypts QQ IMAP authorization codes with AES-256-GCM, while OAuth tokens are stored only as SHA-256 hashes.
Prompt-injection boundary: email bodies are explicitly treated as untrusted external content, and the MCP server instructions prohibit executing instructions found in messages.
Two transports: stdio for local Codex integration and Streamable HTTP for ChatGPT or other MCP clients.
Verifiable behavior: includes six automated tests plus a real QQ Mail end-to-end test script.
Related MCP server: qq-email-mcp
Architecture
flowchart LR
A[ChatGPT / Codex] -->|MCP tools| B[QQ Mail Reader MCP]
B --> C{Runtime mode}
C -->|Local stdio| D[macOS Keychain]
C -->|HTTP + OAuth 2.1| E[Encrypted OAuth Store]
D --> F[QQ Mail IMAP<br/>imap.qq.com:993]
E --> F
B -->|Read-only| FHTTP mode data flow:
MCP Client -> OAuth discovery / DCR / PKCE -> Bearer token -> /mcp
|
v
per-user encrypted credential
|
v
QQ Mail IMAPMCP tools
Tool | Purpose | Changes mailbox state |
| Returns the identity of the connected mailbox | No |
| Checks configuration without returning credentials | No |
| Lists unread message summaries | No |
| Searches by text, sender, subject, date, or read status | No |
| Reads a message body and attachment metadata by mailbox + UID | No |
Every tool declares readOnlyHint: true, destructiveHint: false, and idempotentHint: true.
Quick start
Requirements: Node.js 20+ and a QQ Mail account with IMAP enabled. Use the dedicated IMAP authorization code, not the QQ account password. Never send the authorization code through chat.
Local Codex / MCP client
git clone https://github.com/tqq0531/qq-mail-reader-mcp.git
cd qq-mail-reader-mcp
npm ci
npm run setup
npm startnpm run setup stores the email address and IMAP authorization code in macOS Keychain.
HTTP + OAuth development mode
npm ci
npm run dev:publicThe first run creates a local-only .env.local. Test data is stored in the Git-ignored data/ directory, and QQ IMAP authorization codes are encrypted with AES-256-GCM.
Run the real end-to-end flow in another terminal:
npm run test:manualSee TESTING.md for detailed steps.
Automated tests
npm ci
npm testCurrent coverage includes tool discovery and read-only annotations, encrypted persistence, OAuth discovery, DCR, PKCE, authorization-code exchange, UserInfo, the HTTP 401 challenge, and authenticated MCP calls. Automated tests do not access a real mailbox.
Production deployment
Required container environment variables:
PUBLIC_BASE_URL=https://your-domain.example
MCP_ENCRYPTION_KEY=<32-random-bytes-in-base64>
OAUTH_DB_PATH=/data/oauth-store.json
HOST=0.0.0.0
PORT=8787docker build -t qq-mail-reader-mcp .
docker run --rm -p 8787:8787 --env-file .env.local qq-mail-reader-mcpThe public MCP endpoint is https://your-domain.example/mcp. The deployment environment must allow outbound TCP connections to imap.qq.com:993.
The current JSON persistence layer is intended for single-instance validation. Before a multi-instance production rollout, migrate OAuth clients, accounts, and tokens to PostgreSQL or an equivalent managed database while keeping application-layer encryption for QQ authorization codes.
Current status
✅ Local stdio MCP and macOS Keychain credential loading
✅ Five read-only QQ Mail tools
✅ Multi-user OAuth 2.1 / DCR / PKCE flow
✅ Real QQ IMAP end-to-end validation
✅ Automated tests: 6/6 passing
✅ Dockerfile and Secure MCP Tunnel preflight
🚧 Live ChatGPT Secure MCP Tunnel connection and plugin installation
⏳ PostgreSQL persistence, audit logging, production legal pages, and marketplace submission
See STATUS.md for the detailed milestones and known limitations.
Security
Never commit .env.local, data/, QQ Mail authorization codes, or API keys. See SECURITY.md when reporting a vulnerability, and do not paste credentials into public issues.
License
Available Tools
5 toolsqq_mail_connection_status检查 QQ 邮箱连接配置ARead-onlyIdempotent
检查当前连接是否已配置,只返回邮箱地址和配置状态,绝不返回授权码。
Inputs: no named parameters.
qq_mail_list_unread列出 QQ 邮箱未读邮件ARead-onlyIdempotent
以只读方式列出 QQ 邮箱的未读邮件摘要,不会将邮件标记为已读。返回 mailbox 和 uid,可用于读取指定邮件。
Inputs: limit, mailbox.
qq_mail_profile查看当前 QQ 邮箱连接ARead-onlyIdempotent
返回当前 OAuth 连接对应的 QQ 邮箱身份,帮助区分多个邮箱连接。不返回授权码。
Inputs: no named parameters.
qq_mail_read读取一封 QQ 邮件ARead-onlyIdempotent
使用列表或搜索结果中的 mailbox 和 uid 读取一封邮件的正文与附件元数据,不会下载附件或标记为已读。
Inputs: uid (required), mailbox.
qq_mail_search搜索 QQ 邮箱ARead-onlyIdempotent
按关键词、发件人、主题、日期或未读状态搜索当前已授权的 QQ 邮件,不改变邮件状态。
Inputs: from, text, limit, since, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Most tools have distinct purposes (read, list unread, search, profile, connection status), but qq_mail_profile and qq_mail_connection_status both essentially report identity/connection info and could be confused, and qq_mail_list_unread overlaps with qq_mail_search which also filters by unread state.
All tools share the consistent qq_mail_ prefix, but suffixes mix verb styles (read, list_unread, search) with noun phrases (profile, connection_status), a minor deviation from a pure verb_noun pattern.
Five tools is a well-scoped set for a focused read-only mail reader, with each tool earning its place without redundancy bloat.
As a read-only reader the core read/list/search flows are covered, but there is no way to list mailboxes/folders or list all (read) mail beyond unread, leaving notable gaps in the browse surface.
Maintenance
Related MCP Connectors
Connect any IMAP/SMTP mailbox to Claude & ChatGPT: search, read, sort, draft. Sends only with OK.
Your mailboxes in ChatGPT and Claude: Gmail, iCloud, Fastmail, any IMAP. Passwords stay yours.
Bring Gmail, Outlook, iCloud Mail, Yahoo Mail, Fastmail and other IMAP mailboxes together. Search connected email, including semantic search; cached or indexed results may be incomplete or stale. Read messages and attachments, create drafts, send or reply when requested, and manage rules for new mail. Separate permissions control reading, attachments, drafts, sending and mailbox changes.
Give AI agents their own email inboxes: list, read and send mail via scoped, revocable OAuth grants.
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables AI agents to securely interact with Gmail and QQ Mail, including IMAP search/read/organization, attachments, and preview-confirmed sending.412MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI clients to read, search, manage, and send QQ mailbox emails via IMAP/SMTP, including attachments, drafts, replies, and structured message context for models.58 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables ChatGPT and other OAuth-capable MCP clients to read, search, and send personal QQ or Foxmail mail through a self-hosted server with configurable approval or direct-send modes.MIT
- AlicenseBqualityCmaintenanceReview QQ Mail subscription, renewal and billing notices locally on macOS through a read-only stdio MCP server. Strict TLS and PEEK reads; no sending or mailbox changes. Requires Python 3.13+ and session-only credentials entered through native macOS dialogs; no hosted mailbox or automatic monitoring.51MIT