QQ Mail MCP

English · 简体中文

Read, search, reply to, forward, and send QQ email from ChatGPT or an OAuth-capable MCP agent. Self-hosted with the official Python MCP SDK, TLS IMAP/SMTP, and encrypted SQLite. No OpenAI API key is required.

Each instance binds one @qq.com or @foxmail.com mailbox. All authorized clients access that mailbox.

Quick start

Python 3.12+ and uv are required for running from source.

git clone https://github.com/pythc/qq-mail-mcp.git
cd qq-mail-mcp
uv sync --extra dev --locked
uv run qq-mail-mcp init --url http://localhost:8000
uv run qq-mail-mcp serve

init creates a private .env and refuses to overwrite an existing file. The service admin password is in that file. Open http://localhost:8000, enable IMAP/SMTP in QQ Mail settings, and enter the generated QQ authorization code to bind the mailbox.

For a remote deployment, use an HTTPS domain:

uv run qq-mail-mcp init --url https://mail.example.com --direct-send
docker compose up --build -d

Run either initialization example in a fresh directory, or edit your existing .env. Replace the example domain with your own. Caddy obtains the certificate; allow inbound TCP 80/443 and outbound imap.qq.com:993 and smtp.qq.com:465. See Deployment for prebuilt images, existing proxies, backups and upgrades.

Related MCP server: Mailport

Connect your agent

Open https://your-domain/connect for client-specific buttons, commands and configuration downloads. No mailbox credentials or OAuth tokens are embedded in the installation links.

The buttons install configuration; they do not bypass your client's trust or OAuth consent. ChatGPT has no universal installation deeplink. A public HTTPS deployment and an account with the appropriate connection feature are needed; ChatGPT cannot reach your localhost.

You can also generate instructions locally:

uv run qq-mail-mcp connect cursor --url https://mail.example.com --open
uv run qq-mail-mcp connect vscode --url https://mail.example.com --open
uv run qq-mail-mcp connect codex --url https://mail.example.com
uv run qq-mail-mcp connect claude-code --url https://mail.example.com

First OAuth authorization opens this service's consent page. Enter the service admin password, not the QQ password or IMAP authorization code. CIMD and DCR registration, S256 PKCE, issuer-bound responses, token refresh and revocation are supported. Scopes: qq-mail.read, qq-mail.send.

Sources: Cursor install links, VS Code install links, Codex MCP, Claude Code MCP, ChatGPT OAuth. Client interfaces change; configuration generation is tested, but installation and OAuth behavior must be checked with your installed client version.

Tools

In browser-approval mode, reply_email and forward_email prepare a draft for approval rather than sending it immediately.

Reading and attachments

Pass the uid, uidvalidity and folder returned by a listing. For stable pagination, pass next_cursor with the same filters and offset=0; UIDVALIDITY changes require a new listing.

A large attachment no longer blocks body reading. Each body page returns up to 30,000 characters; use next_body_offset to continue. The selected encoded text part is bounded to 2 MiB, indicated by source_truncated. Attached messages are downloadable attachments, not recursively expanded text. HTML is converted to text without fetching remote images or executing scripts. Chinese search requires QQ's UTF-8 IMAP SEARCH support.

download_attachment returns data_base64; encoded MIME parts are limited to 8 MiB. Outgoing attachments use name, content_type, data_base64; at most 5 files, totaling 5 MiB decoded. Send bodies are plain text, up to 100,000 characters. HTML sending, deleting and moving mail are not supported. Forwarding fails explicitly if the body is truncated or attachment limits are exceeded.

Sending and deduplication

Server settings do not override client-side tool confirmation. Outgoing actions must be requested by the user.

Example send_email arguments:

{
  "request_id": "0ef834bf-09f1-4ff5-9cf0-1178d3d2eb65",
  "to": ["recipient@example.com"],
  "subject": "Meeting time",
  "body": "See you tomorrow at 3 PM."
}

Generate one UUID per intended email; retries reuse the original ID and contents. Encrypted direct-send records last seven days and are scoped to the OAuth client. Query get_send_status(request_id=...) for direct sends or get_send_status(draft_id=...) for prepared drafts. Approval drafts expire after 30 minutes. accepted means SMTP acceptance, not guaranteed delivery or an entry in QQ's Sent folder. partially_accepted lists refused recipients. sending and unknown may mean delivery occurred: do not automatically retry with a new ID.

Owner management

Open /manage and sign in to view the bound mailbox, send mode, authorized clients and recent outgoing records. You can check IMAP connectivity, revoke a client's access, and sign out. Owner sessions expire after one hour. Sending mode remains deployment-controlled. Public pages do not disclose the mailbox address or credentials. English is the default for setup, connections and management; ?lang=zh selects Chinese.

Data and maintenance

SQLite encrypts mailbox credentials, OAuth state, drafts, attachments in outgoing drafts and send receipts. Received bodies and downloads are not retained. Read-only EXAMINE and BODY.PEEK preserve read status. Changing a browser-bound mailbox revokes old grants and drafts; same-mailbox code rotation preserves them. Environment binding requires both QQ_EMAIL and QQ_AUTH_CODE; changing it requires a separate database and fresh client authorization.

uv run qq-mail-mcp backup /private/path/snapshot.sqlite3
# Stop the service first; restore with the original encryption key:
uv run qq-mail-mcp restore /private/path/snapshot.sqlite3 --confirm-offline

Snapshots must be stored privately; keep the encryption key separately. Restore refuses mismatched keys and retains a snapshot of the previous database. Never restore an older send ledger and resume sending blindly: operations after that snapshot might already have reached SMTP. See Deployment for default Docker named-volume procedures. Authentication routes have bounded per-peer and global traffic limits; behind a reverse proxy, peers may share a limit. Received mail is untrusted source data, never instructions to execute.

Development

uv sync --extra dev --locked
uv run ruff check .
uv run ruff format --check .
uv run pytest
uv build

Tests use simulated IMAP/SMTP and do not send real messages. They cover MIME part reading, attachment limits, threading, receipts, concurrent send deduplication, restart behavior, DCR/CIMD OAuth, revocation, owner sessions, connection recipes and backup/restore. CI also validates packaging and Docker. Validate real QQ access and your client after deployment. Refresh cached tool lists after upgrades.

MIT License. See Contributing, Security and Changelog. Report vulnerabilities privately; never include real credentials or messages in public issues.