Skip to main content
Glama
qzone-mcp

qzone-mcp

by inzzou

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.

Related MCP server: qq-mcp-server

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 .
  1. 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.

Available Tools

12 tools
qzone_commentC

评论一条说说。

Inputs: fid (required), content (required), hostuin (required), appid.

qzone_confirm_publishA

使用 qzone_prepare_publish 返回的 token 执行一次真实发布;token 使用一次即失效。

Inputs: confirmation_token (required).

qzone_deleteC

删除当前登录 QQ 自己发布的说说。

Inputs: fid (required), appid, created_at.

qzone_get_postC

读取一条说说详情。

Inputs: fid (required), hostuin (required), appid.

qzone_likeC

点赞或取消点赞一条说说。为兼容旧调用保留 unlike 参数。

Inputs: fid (required), hostuin (required), appid, unlike.

qzone_list_postsA

读取 QQ 空间动态。hostuin=0 表示好友动态流;指定 QQ 号时读取其空间。

Inputs: limit, cursor, hostuin.

qzone_prepare_publishA

只生成发布预览,不会真的发说说;返回短时 confirmation_token,确认后调用 qzone_confirm_publish。

Inputs: content (required), images.

qzone_publishA

直接发布 QQ 空间说说。images 支持多张本机图片绝对路径;如需发前确认,请改用 qzone_prepare_publish。

Inputs: content (required), images.

qzone_reply_commentC

回复一条说说评论。

Inputs: fid (required), content (required), hostuin (required), commentid (required), +2 more.

qzone_statusA

检查 QZone daemon、NapCat 登录凭证和绑定状态;不会返回 Cookie/CSRF。

Inputs: no named parameters.

qzone_unlikeB

取消点赞一条说说。

Inputs: fid (required), hostuin (required), appid.

qzone_visitorsC

读取当前 QQ 空间最近访客。

Inputs: page, count.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 12 tools

    Disambiguation4/5

    工具总体边界清晰,按帖子、点赞、评论、访客等资源区分明确。但 qzone_like 兼容 unlike 参数与独立 qzone_unlike 功能重叠,可能在取消点赞时造成选择歧义。

    Naming Consistency4/5

    大多数工具遵循 qzone_<动词> 的 snake_case 命名,整体可预测。但 qzone_status 和 qzone_visitors 是名词形式,qzone_delete 也缺少明确宾语,存在少量不一致。

    Tool Count5/5

    12 个工具覆盖状态检查、说说读写、点赞评论和访客信息,规模适中。即使包含 prepare/confirm 两步发布和独立 unlike,也没有臃肿感,每个工具都有明确用途。

    Completeness4/5

    覆盖了说说读取、发布、删除以及点赞、评论、回复、访客等核心社交动作,整体闭环较完整。但缺少更新说说、独立评论列表和删除评论等能力,属于可绕过的小缺口。

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      An MCP server that enables AI clients to send and receive QQ messages through NapCatQQ (OneBot v11) for both private and group chats. It supports message context management, real-time WebSocket listening, and human-like typing simulation.
      7
      26
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A MCP server that exposes QQ bot capabilities over Streamable HTTP, enabling clients to query bot status, read group and friend info, fetch chat history, and send group/private text messages.
      3
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables authenticated querying of QQ Zone profiles, posts, statistics, albums, and message boards through MCP tools, with cookie management and optional HTTP/SSE access.
      -