QQ Mail Read-only MCP

Local-first QQ Mail access for subscription, renewal and billing notices.

Created and maintained by Chuluu.

中文说明 | English

Downloads · Distribution · Installation · Testing · Privacy · Security · Changelog

What it does

This small MCP server helps an AI assistant find and read mail about subscriptions, upcoming renewals, billing, price changes and cancellation deadlines. It supplies mail access; the included Agent Skill guides a review and cites the source message. It does not automatically classify every message, cancel subscriptions or send notifications.

• Lists mailbox folders, including modified UTF-7 names.

• Searches by date, decoded sender and subject, with Chinese MIME support.

• Saves ascending UID snapshots for stable, restartable pagination.

• Reads bounded MIME text and inert HTML with UID + UIDVALIDITY and PEEK.

• Replays unacknowledged incremental batches and advances local checkpoints after explicit acknowledgment.

• Uses strict TLS verification and EXAMINE; no mail sending or mailbox mutation tools.

0.1.0 · MIT open-source prototype. The runtime uses Python 3.13+ and its standard library. Each user runs their own process and uses their own QQ account. There is no hosted credential service, public listener, daemon or automatic monitoring.

Related MCP server: qq-email-mcp

Quick start

git clone https://github.com/ChuluuMGL/qqmail-readonly-mcp.git
cd qqmail-readonly-mcp
python3 -m unittest discover -s tests -v
python3 scripts/run_mcp.py

The final command starts an unauthenticated stdio server: initialization and tool discovery work offline; mail calls return CREDENTIALS_NOT_CONFIGURED. EOF stops it.

On macOS, use session-only native masked credential input when connecting an MCP client:

python3 scripts/run_mcp.py --secure

The first dialog asks for an email address or QQ number; the second asks for an IMAP authorization code. Do not paste the code into chat, tool arguments, configuration files or Git. The process keeps it in memory until the session ends. See client setup; typing the command alone does not attach tools to an AI client.

Tools

Dates use IMAP INTERNALDATE: since inclusive, before exclusive, YYYY-MM-DD. Sender and subject matching runs locally against decoded MIME headers; narrow the date range for large mailboxes. Resume with the returned cursor. New mail appears in a fresh query rather than changing an existing snapshot.

Safety and limits

Raw messages are limited to 2 MiB and headers to 64 KiB. At most 100,000 UIDs are allowed in a search; an IMAP response-line limit can reject very large results earlier. Socket I/O has a 15-second timeout and one reconnection attempt; long header scans have no total task deadline. Attachments are not downloaded separately.

Email and HTML are untrusted data. The server never executes scripts or loads external resources. Client summaries and model processing may transmit selected mail content according to that client's settings; local IMAP execution does not imply the whole AI workflow stays offline.

Delivery is at least once: persist downstream results idempotently by account/folder/UIDVALIDITY/UID, then acknowledge the complete receipt. Do not deduplicate by Message-ID alone. UIDVALIDITY changes require a fresh namespace. Run one process per state directory; snapshots currently have no automatic pruning.

Plugin and deployment scope

The repository includes portable plugin.json / mcp.json, a Codex compatibility manifest and a subscription-review Skill. The bundled masked-input launcher targets macOS; the core server can use credentials from an approved process-environment provider on other systems. See installation and compatibility.

This repository is not listed in the official ChatGPT/Codex directory. Local plugin installation does not automatically give dot or cloud ChatGPT access to this Mac. Remote access needs separately authorized infrastructure such as Secure MCP Tunnel and an online machine. Sites alone cannot open ordinary raw TCP connections to QQ IMAP. No such infrastructure is provisioned here.

Maintenance, copyright and license

Created and maintained by Chuluu.

Copyright (c) 2026 Chuluu. Project source and documentation use the MIT License; see NOTICE and third-party notices. Built with AI-assisted coding and maintainer review. This independent project is not an official Tencent or OpenAI product.

Issues and pull requests are welcome; see contributing. Please keep all examples synthetic.

A macOS MCPB desktop bundle is also available in Releases. It requires an existing Python 3.13+ installation. See platform submission status. Directory acceptance and desktop-client ingestion are separate from GitHub publication.