Skip to main content
Glama

gzh-mcp

微信公众号管理 MCP server。把草稿发布、素材、统计、用户标签、菜单、评论、 群发、定向推送与常用基础接口封装成标准 MCP 工具,供本机 MCP 客户端(Claude Code、Codex CLI 等)调用。

  • 不做排版:create_draft 接受 HTML,Markdown → 微信 HTML 由调用方完成。

  • 完整启用后共 59 个工具;自动发布和群发分别受独立环境变量控制。

  • 不持久化业务状态;只有下载工具会按调用方指定的路径写文件,且拒绝覆盖。

  • 凭据只从环境变量注入,错误信息中的 secret 和 access token 会脱敏。

工具清单

域

工具

注册规则

v1 草稿发布(10)

check_credentials、upload_content_image、upload_cover_image、create_draft、get_draft、update_draft、list_drafts、publish_draft、get_publish_status、list_published

除 publish_draft 外默认注册

发布补充(3)

delete_draft、get_published_article、delete_published_article

默认注册;删除需 confirm=true

素材(8)

upload_video_material、upload_voice_material、get_material、delete_material、list_materials、count_materials、upload_temp_media、download_temp_media

默认注册;删除需确认,下载拒绝覆盖已有文件

数据统计(1)

get_statistics_report

默认注册;支持的 report 与时间跨度会前置校验

用户与标签(14)

list_users、get_user_info、batch_get_user_info、update_user_remark、create_tag、list_tags、update_tag、delete_tag、get_user_ids_by_tag、tag_users、untag_users、list_blacklist、blacklist_users、unblacklist_users

默认注册;删除标签需确认

菜单(6)

create_menu、get_current_menu、delete_menu、create_conditional_menu、delete_conditional_menu、try_match_conditional_menu

默认注册;删除需确认

评论(4)

open_comment、list_comments、mark_comment_elect、unmark_comment_elect

默认注册

群发(6)

mass_send_all、mass_send_by_tag、mass_send_by_openids、preview_mass_message、get_mass_status、delete_mass_message

前 4 个需开启群发闸门;发送还需 clientmsgid 与确认;状态查询和删除默认注册

定向推送(3)

send_custom_message、send_template_message、send_subscribe_message

默认注册;每次发送需 confirm=true

杂项(4)

create_qrcode、get_jsapi_ticket、get_autoreply_config、get_server_ips

默认注册

明确不实现:sns/*、shorturl、getarticletotal、群发速度配置、模板行业配置、 genShortKey、Markdown 排版与内容合规检查。

Related MCP server: mcp-server-wechat-mp

安全模型

发布、群发、定向推送和删除会改变外部状态,本 server 采用以下控制:

  1. 注册闸门(安装时):环境变量 GZH_MCP_ALLOW_PUBLISH 为 1 或小写 true(严格匹配,0/false/TRUE/空串均不生效)时,publish_draft 才会出现在工具列表。MCP 客户端缓存工具列表,修改后需重启客户端。

  2. 确认闸门(每次调用):publish_draft 必须显式传 confirm=true, 否则直接拒绝,不发出任何 HTTP 请求。

  3. 群发双闸门:GZH_MCP_ALLOW_MASS_SEND 必须严格为 1 或小写 true, mass_send_all、mass_send_by_tag、mass_send_by_openids、 preview_mass_message 才注册;前三者还必须传非空 clientmsgid 和 confirm=true。

  4. 逐次确认:删除类工具以及客服、模板、订阅通知发送工具必须显式传 confirm=true;校验失败不会发 HTTP 请求。

其他安全相关行为:

  • WECHAT_SECRET 与 access_token 全链路脱敏,不出现在错误信息、日志或 stdout;stdout 只承载 MCP JSON-RPC 协议,诊断信息一律写 stderr。

  • 错误详情对调用方可见:微信业务错误(errcode、errmsg、接口路径)、本地 校验拒绝与 confirm 闸门拒绝理由都完整返回给 MCP 调用方,不会被 SDK 掩码成通用的 Error executing tool。

  • 非幂等接口(创建草稿、发布、群发与定向推送)遇网络传输错误返回 「状态不确定」错误并禁止自动重试,防止重复建稿、重复提交。

  • 只读接口遇传输错误、HTTP 5xx 或微信 errcode=-1 时最多退避重试一次。

  • create_draft 前置拦截:非微信域正文图 URL(微信会过滤外链图)、 <script>、超长标题/摘要/正文;图片按文件魔数校验真实格式。

  • 创建草稿后自动回读验证(标题、图片数、正文长度),微信清洗了内容时 返回 verified=false + 差异详情,不静默成功。

  • create_draft 同时校验普通图文和 article_type=newspic 图片帖;图片帖要求 1–20 个非空 image_media_id,回读时核对图片数。

  • 发布结果带脱敏 appid 前缀、草稿标题、media_id,便于调用方核对目标账号。

前置要求

  • Python 3.12+ 与 uv

  • 公众号的 AppID / AppSecret(公众平台官网 → 设置与开发 → 基本配置)

  • IP 白名单:获取 access_token 的出口 IP 必须加入公众号 IP 白名单, 否则报 40164

  • 发布权限:freepublish/* 仅对已认证账号开放,个人主体/未认证账号 通常返回 48001。草稿与素材接口不受此限制

安装

git clone https://github.com/onlyoasis/gzh-mcp.git
cd gzh-mcp
uv sync
uv run pytest   # 验证安装

客户端配置

MCP 客户端的 stdio server 配置(JSON):

{
  "mcpServers": {
    "gzh": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/gzh-mcp", "gzh-mcp"],
      "env": {
        "WECHAT_APPID": "<你的 AppID>",
        "WECHAT_SECRET": "<你的 AppSecret>",
        "GZH_MCP_PROXY": "http://127.0.0.1:2080",
        "GZH_MCP_ALLOW_PUBLISH": "0",
        "GZH_MCP_ALLOW_MASS_SEND": "0"
      }
    }
  }
}

Claude Code 也可用命令行注册:

claude mcp add gzh -s user \
  -e WECHAT_APPID=<你的 AppID> \
  -e WECHAT_SECRET=<你的 AppSecret> \
  -- uv run --directory /path/to/gzh-mcp gzh-mcp

环境变量

变量

必填

说明

WECHAT_APPID

是

公众号 AppID

WECHAT_SECRET

是

AppSecret,仅经环境变量注入,不落任何文件

GZH_MCP_PROXY

否

显式 HTTP(S) 代理;server 不继承宿主代理环境,适用于固定出口 IP 白名单

GZH_MCP_ALLOW_PUBLISH

否

1/true 注册 publish_draft;其余值一律视为关闭

GZH_MCP_ALLOW_MASS_SEND

否

1/true 注册 4 个群发发送/预览工具;其余值一律视为关闭

典型工作流

发布一篇已排版的文章(HTML):

1. check_credentials                → 确认凭据与 IP 白名单正常
2. upload_cover_image(cover.png)    → 得到 thumb_media_id
3. upload_content_image(a.png) ...  → 得到微信图片 URL,替换正文中的 src
4. create_draft([{title, content,   → 创建草稿,返回 media_id + verified
    thumb_media_id, digest}])
5. 人工在公众号后台复核草稿,发布

开启自动发布后(GZH_MCP_ALLOW_PUBLISH=1):

6. publish_draft(media_id, confirm=true) → 提交发布,返回 publish_id
7. get_publish_status(publish_id)        → 轮询:0 成功 / 1 发布中 /
                                           2 原创失败 / 3 常规失败 /
                                           4 审核不通过 / 5、6 成功后被删/封禁

已知约定与限制

  • server 无本地状态:media_id → publish_id 映射由调用方记录,事后对账用 list_published。

  • file_path 参数指 MCP server 所在主机的本地文件;server 与客户端须同机, 不支持远程部署(若需远程部署,必须先重新评审文件路径信任边界)。

  • get_material、download_temp_media 的 save_path 也位于 MCP server 主机; 自动创建父目录,但目标文件存在时拒绝覆盖。

  • 发布为异步语义:提交成功(拿到 publish_id)不等于文章发布成功,以 get_publish_status 终态为准。

  • 正文图限制:jpg/png 且严格小于 1MB;封面支持 jpg/png/gif/bmp,≤10MB。

  • 标题和正文必须非空,长度交由微信平台按当前真实契约校验;摘要官方上限 128 字符(本工具按 120 保守限制)。正文仍前置拒绝脚本和非微信图片 URL。

开发

uv sync                                    # 安装依赖
uv run pytest                              # 全量测试
uv run pytest --cov=gzh_mcp --cov-report=term-missing   # 覆盖率
uv run gzh-mcp                             # 本地启动(stdio)

测试全部使用 mock,不会真实调用微信 API。本项目要求回归测试通过 「红灯验证」:修改行为前先确认对应测试在退化实现下真的失败。

文档

License

MIT

Available Tools

53 tools
batch_get_user_infoA
Read-onlyIdempotent

批量获取用户基本信息。

Inputs: openid_list (required). Returns: object

blacklist_usersC

批量拉黑用户。

Inputs: openid_list (required). Returns: object

check_credentialsA
Read-onlyIdempotent

验证公众号凭据和 IP 白名单;成功不代表拥有发布权限。

Inputs: no named parameters. Returns: object

count_materialsA
Read-onlyIdempotent

获取各类型永久素材数量。

Inputs: no named parameters. Returns: object

create_conditional_menuC

创建个性化菜单。

Inputs: buttons (required), match_rule (required). Returns: object

create_draftA

前置校验后创建一个或多个图文草稿,并自动回读验证。

Inputs: articles (required). Returns: object

create_menuC

创建默认自定义菜单。

Inputs: buttons (required). Returns: object

create_qrcodeC

创建临时或永久参数二维码。

Inputs: action_name (required), scene_id, scene_str, expire_seconds. Returns: object

create_tagB

创建用户标签。

Inputs: name (required). Returns: object

delete_conditional_menuA
Destructive

删除个性化菜单;必须显式确认。

Inputs: menu_id (required), confirm. Returns: object

delete_draftA
Destructive

删除草稿;必须显式确认。

Inputs: media_id (required), confirm. Returns: object

delete_mass_messageA
Destructive

删除群发消息;必须显式确认。

Inputs: msg_id (required), confirm, article_idx. Returns: object

delete_materialA
Destructive

删除永久素材;必须显式确认。

Inputs: media_id (required), confirm. Returns: object

delete_menuA
Destructive

删除默认自定义菜单;必须显式确认。

Inputs: confirm. Returns: object

delete_published_articleA
Destructive

删除已发表文章或其中一篇;必须显式确认。

Inputs: article_id (required), index, confirm. Returns: object

delete_tagA
Destructive

删除用户标签;必须显式确认。

Inputs: tag_id (required), confirm. Returns: object

download_temp_mediaA
Read-onlyIdempotent

获取临时素材;二进制响应写入本机 save_path 且不覆盖。

Inputs: media_id (required), save_path (required). Returns: object

get_autoreply_configA
Read-onlyIdempotent

获取公众号当前自动回复配置。

Inputs: no named parameters. Returns: object

get_current_menuA
Read-onlyIdempotent

获取当前自定义菜单。

Inputs: no named parameters. Returns: object

get_draftB
Read-onlyIdempotent

读取草稿的完整 news_item 数组。

Inputs: media_id (required). Returns: object

get_jsapi_ticketB
Read-onlyIdempotent

获取 JS-SDK 的 jsapi_ticket。

Inputs: no named parameters. Returns: object

get_mass_statusB
Read-onlyIdempotent

查询群发消息发送状态。

Inputs: msg_id (required). Returns: object

get_materialA
Read-onlyIdempotent

获取永久素材;二进制响应写入本机 save_path 且不覆盖。

Inputs: media_id (required), save_path (required). Returns: object

get_published_articleA
Read-onlyIdempotent

按 article_id 获取单篇已发表文章。

Inputs: article_id (required). Returns: object

get_publish_statusA
Read-onlyIdempotent

按 publish_id 查询异步发布状态。

Inputs: publish_id (required). Returns: object

get_server_ipsA
Read-onlyIdempotent

获取微信服务器回调 IP 列表。

Inputs: no named parameters. Returns: object

get_statistics_reportA
Read-onlyIdempotent

按 report 获取公众号统计数据,并前置校验日期跨度。

Inputs: report (required), end_date (required), begin_date (required). Returns: object

get_user_ids_by_tagA
Read-onlyIdempotent

分页获取指定标签下的关注者 OpenID。

Inputs: tag_id (required), next_openid. Returns: object

get_user_infoA
Read-onlyIdempotent

获取单个用户基本信息。

Inputs: openid (required), lang. Returns: object

list_blacklistA
Read-onlyIdempotent

分页获取公众号黑名单。

Inputs: next_openid. Returns: object

list_commentsB
Read-onlyIdempotent

分页读取已发表文章评论。

Inputs: index (required), msg_data_id (required), begin, count, +1 more. Returns: object

list_draftsB
Read-onlyIdempotent

分页列出草稿,并通过 draft/count 附带草稿总数。

Inputs: count, offset. Returns: object

list_materialsA
Read-onlyIdempotent

分页列出指定类型的永久素材。

Inputs: material_type (required), count, offset. Returns: object

list_publishedA
Read-onlyIdempotent

分页列出成功发布的文章,用于无状态对账。

Inputs: count, offset. Returns: object

list_tagsA
Read-onlyIdempotent

列出公众号全部用户标签。

Inputs: no named parameters. Returns: object

list_usersA
Read-onlyIdempotent

分页获取关注者 OpenID。

Inputs: next_openid. Returns: object

mark_comment_electC

将评论标记为精选。

Inputs: index (required), msg_data_id (required), user_comment_id (required). Returns: object

send_custom_messageB
Destructive

发送客服消息;必须显式确认。

Inputs: openid (required), message (required), confirm. Returns: object

send_subscribe_messageC
Destructive

发送订阅通知;必须显式确认。

Inputs: data (required), openid (required), template_id (required), page, +2 more. Returns: object

send_template_messageC
Destructive

发送模板消息;必须显式确认。

Inputs: data (required), openid (required), template_id (required), url, +2 more. Returns: object

tag_usersB

批量为用户添加标签。

Inputs: tag_id (required), openid_list (required). Returns: object

try_match_conditional_menuB
Read-onlyIdempotent

测试指定用户会匹配到的个性化菜单。

Inputs: user_id (required). Returns: object

unblacklist_usersC

批量取消拉黑用户。

Inputs: openid_list (required). Returns: object

unmark_comment_electC

取消评论精选。

Inputs: index (required), msg_data_id (required), user_comment_id (required). Returns: object

untag_usersC

批量取消用户标签。

Inputs: tag_id (required), openid_list (required). Returns: object

update_draftB

按从 0 开始的文章位置更新草稿。

Inputs: index (required), article (required), media_id (required). Returns: object

update_tagC

更新用户标签名。

Inputs: name (required), tag_id (required). Returns: object

update_user_remarkC

更新用户备注名。

Inputs: openid (required), remark (required). Returns: object

upload_content_imageA

上传本机 JPG/PNG 正文图片并返回微信图片 URL。

Inputs: file_path (required). Returns: object

upload_cover_imageA

上传本机图片为永久封面素材并返回 media_id。

Inputs: file_path (required). Returns: object

upload_temp_mediaB

上传图片、语音、视频或缩略图临时素材。

Inputs: file_path (required), media_type (required). Returns: object

upload_video_materialA

上传本机 MP4 为永久视频素材。

Inputs: title (required), file_path (required), introduction (required). Returns: object

upload_voice_materialA

上传本机音频为永久语音素材。

Inputs: file_path (required). Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 53 tools

    Disambiguation4/5

    Most tools are clearly separated by resource type (drafts, published articles, materials, users, tags, menus, comments, messages), so an agent can usually distinguish them by the object noun. A few boundary overlaps exist—upload_temp_media versus upload_video_material/upload_voice_material, and get_publish_status versus get_mass_status—but the descriptions provide enough clarification.

    Naming Consistency4/5

    The set consistently uses snake_case verb_noun naming, such as create_draft, delete_material, list_tags, and get_user_info. Minor deviations include batch_get_user_info, try_match_conditional_menu, and inconsistent use of material versus media for similar upload concepts, but these do not seriously undermine the overall pattern.

    Tool Count1/5

    53 tools is far beyond a well-scoped MCP surface and falls into the extreme count category. While the WeChat Official Account domain is broad, exposing this many individual operations makes tool selection heavy and risks overwhelming agents.

    Completeness2/5

    The set covers many API areas but has critical lifecycle gaps: there is no tool to submit or publish a draft, no send-mass-message tool, and no reply/delete-comment operation. These omissions create dead ends, such as creating a draft without the ability to publish it or querying mass-message status without the ability to send a mass message.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers