Skip to main content
Glama
ChuluuMGL

QQ Mail Read-only MCP

by ChuluuMGL
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

QQ Mail Read-only MCP

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

Created and maintained by Chuluu.

中文说明 | English

Version License: MIT by Chuluu Read-only

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: Mail Agent 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

Tool

Purpose

list_folders

List folders and whether they can be selected.

search_mail

Date/sender/subject search with a persistent cursor; page size 1–100.

read_mail

Read a UID in an explicitly identified UIDVALIDITY namespace.

check_incremental

Create or replay a durable pending UID batch.

acknowledge_checkpoint

Confirm downstream processing and update only local delivery state.

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.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-imap-server

    mattias242
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables LLMs to read, search, and manage emails via IMAP with secure, read-only access to email accounts.
    6
    -

  • Mail Agent MCP

    SinoEdwards
    A
    license
    B
    quality
    B
    maintenance
    Enables AI agents to securely interact with Gmail and QQ Mail, including IMAP search/read/organization, attachments, and preview-confirmed sending.
    41
    2
    MIT

  • postfach-mcp

    unstko
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI assistants to securely access IMAP mailboxes with read-focused tools for searching, reading, listing messages, and creating drafts, while deliberately preventing sending or deleting emails.
    MIT

  • qq-email-mcp

    xieningqing
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI clients to read, search, manage, and send QQ mailbox emails via IMAP/SMTP, including attachments, drafts, replies, and structured message context for models.
    53 npm
    MIT