qzone-mcp

Independent local MCP wrapper for astrbot_plugin_qzone_ultra + NapCat.

This is an independent community integration. It is not affiliated with, endorsed by, or maintained by QZoneUltra, NapCatQQ, AstrBot, or Tencent.

Architecture:

Codex -> MCP (stdio) -> adapter -> QzoneUltra daemon (127.0.0.1) -> QZone

NapCat (127.0.0.1) -> credentials -> adapter -> daemon /bind

The Ultra source is treated as an external dependency and is not modified or copied into this project.

Credits and licensing

• astrbot_plugin_qzone_ultra is an external runtime dependency by 雪碧bir, licensed under MIT. Its source is not bundled in this repository.
• NapCatQQ supplies the external QQ login and OneBot runtime. Its source and binaries are not bundled in this repository. Users must install it separately and comply with its own Limited Redistribution License, including its non-commercial-use terms.
• This MCP wrapper is licensed under the MIT license in LICENSE.

See THIRD_PARTY_NOTICES.md for the exact upstream references used by this project.

Safety boundary

• NapCat and Qzone daemon URLs are rejected unless they use 127.0.0.1 or localhost.
• Cookie/CSRF values are only used internally for daemon binding.
• MCP results are recursively sanitized to remove credential-like keys.
• Cookie values are not intentionally logged.

Install

1. Keep/clone QzoneUltra somewhere on disk and install its own requirements there.
2. Install this MCP:

cd D:\qzone-mcp
python -m pip install -e .

3. Set environment variables from .env.example in your Codex MCP configuration.

Example Codex MCP config:

[mcp_servers.qzone]
command = "python"
args = ["-m", "qzone_mcp"]

[mcp_servers.qzone.env]
NAPCAT_URL = "http://127.0.0.1:3000"
NAPCAT_TOKEN = "YOUR_NAPCAT_TOKEN"
QZONE_ULTRA_ROOT = "D:\\path\\to\\astrbot_plugin_qzone_ultra"
QZONE_DATA_DIR = "D:\\qzone-mcp-data"
QZONE_MEDIA_ROOT = "D:\\qzone-mcp-media"
QZONE_DAEMON_PORT = "18999"
QZONE_AUTO_START_DAEMON = "true"
QZONE_AUTO_BIND = "true"

If an Ultra daemon is already running, set QZONE_DAEMON_SECRET to the same secret and optionally set QZONE_AUTO_START_DAEMON=false.

First test

Ask Codex to call qzone_status first. It should verify:

• local daemon reachable;
• NapCat returns the logged-in QQ number;
• QZone cookie exists;
• p_skey exists if NapCat exposes the required QZone cookie;
• daemon accepts the internal bind.

Only after that call qzone_publish.

Tools in v0.3

• qzone_status
• qzone_list_posts
• qzone_get_post
• qzone_publish (direct publish; text + multiple local images)
• qzone_prepare_publish (preview only; returns one-time confirmation token)
• qzone_confirm_publish (publishes a prepared preview)
• qzone_like
• qzone_unlike
• qzone_comment
• qzone_reply_comment
• qzone_delete
• qzone_visitors

Video is intentionally left out of the first version.

v0.2 notes

• Keeps the existing direct publish flow unchanged.
• Adds an optional two-step preview/confirm publish flow to reduce accidental posts.
• Retries once with a fresh NapCat QZone credential bind when the daemon reports an authentication/login failure.
• Tightens local-only URL validation using parsed loopback hostnames (including ::1) instead of string prefixes.
• Multi-image input continues to use the existing images: list[str] path and is validated against QZONE_MEDIA_ROOT.
• QZONE_PUBLISH_PREVIEW_TTL controls preview-token lifetime in seconds (default 600).

v0.3 notes

• Keeps all v0.2 behavior and APIs unchanged.
• Confirms feed listing, post detail, comments, replies, delete, and like flows are exposed as MCP tools.
• Adds a dedicated qzone_unlike tool so agents do not need to remember unlike=true.