gzh-mcp
One-line summary: This MCP server lets an MCP client (Claude Code, Codex CLI, etc.) operate a WeChat Official Account — creating drafts, uploading materials, reading analytics, managing users/tags/menus/comments, and sending messages, with publish and mass-send gated behind env flags and per-call confirm=true.
Drafts & publishing (12 tools): verify credentials/IP whitelist (
check_credentials), upload content images and covers,create_draft(with pre-validation of HTML, non-WeChat image URLs,<script>, length limits, and auto read-back verification), read/update/list drafts, pollget_publish_status, list published articles, and delete drafts or published articles (confirm required). Notepublish_draftis not in this schema — it only registers whenGZH_MCP_ALLOW_PUBLISH=1.Materials (8 tools): upload permanent video/voice materials and temp media (image/voice/video/thumb), list/count materials, fetch a material or temp media binary to a local
save_path(never overwrites), delete materials (confirm required).Statistics (1 tool):
get_statistics_reportfor official-account stats with pre-validated report type and date span.Users & tags (14 tools): list followers, get/batch-get user info, update remarks, create/list/update/delete tags, list users by tag, batch tag/untag users, list/blacklist/unblacklist users.
Menus (6 tools): create/get/delete default menus, create/delete personalized (conditional) menus, and test which conditional menu a user matches.
Comments (3 tools registered): list article comments, mark/unmark comments as featured (
open_commentis not present in this schema).Mass messaging (2 tools registered): query mass-send status and delete a mass message (confirm required). The
mass_send_*/preview_mass_messagetools only register whenGZH_MCP_ALLOW_MASS_SEND=1, and sending also needs a non-emptyclientmsgidplusconfirm=true.Targeted push (3 tools): send customer-service, template, and subscribe messages — each requires
confirm=true.Misc (4 tools): create temporary/permanent QR codes with scene params, get
jsapi_ticket, read auto-reply config, and fetch WeChat callback server IPs.
Key constraints to keep in mind: the server is stateless (you must record media_id → publish_id and reconcile with list_published), publishing is asynchronous (success means a publish_id, not a live article), file_path/save_path refer to the MCP server host so it must run on the same machine as the client, and non-idempotent calls return an "uncertain state" error on transport failure and must not be retried.
Provides tools for managing and publishing WeChat Official Account content, including uploading content and cover images, creating/updating/listing drafts, submitting drafts for publication, and checking publish status.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gzh-mcp create a draft from this HTML and verify it"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
gzh-mcp
微信公众号管理 MCP server。把草稿发布、素材、统计、用户标签、菜单、评论、 群发、定向推送与常用基础接口封装成标准 MCP 工具,供本机 MCP 客户端(Claude Code、Codex CLI 等)调用。
不做排版:
create_draft接受 HTML,Markdown → 微信 HTML 由调用方完成。完整启用后共 59 个工具;自动发布和群发分别受独立环境变量控制。
不持久化业务状态;只有下载工具会按调用方指定的路径写文件,且拒绝覆盖。
凭据只从环境变量注入,错误信息中的 secret 和 access token 会脱敏。
工具清单
域 | 工具 | 注册规则 |
v1 草稿发布(10) |
| 除 |
发布补充(3) |
| 默认注册;删除需 |
素材(8) |
| 默认注册;删除需确认,下载拒绝覆盖已有文件 |
数据统计(1) |
| 默认注册;支持的 report 与时间跨度会前置校验 |
用户与标签(14) |
| 默认注册;删除标签需确认 |
菜单(6) |
| 默认注册;删除需确认 |
评论(4) |
| 默认注册 |
群发(6) |
| 前 4 个需开启群发闸门;发送还需 |
定向推送(3) |
| 默认注册;每次发送需 |
杂项(4) |
| 默认注册 |
明确不实现:sns/*、shorturl、getarticletotal、群发速度配置、模板行业配置、
genShortKey、Markdown 排版与内容合规检查。
Related MCP server: mcp-server-wechat-mp
安全模型
发布、群发、定向推送和删除会改变外部状态,本 server 采用以下控制:
注册闸门(安装时):环境变量
GZH_MCP_ALLOW_PUBLISH为1或小写true(严格匹配,0/false/TRUE/空串均不生效)时,publish_draft才会出现在工具列表。MCP 客户端缓存工具列表,修改后需重启客户端。确认闸门(每次调用):
publish_draft必须显式传confirm=true, 否则直接拒绝,不发出任何 HTTP 请求。群发双闸门:
GZH_MCP_ALLOW_MASS_SEND必须严格为1或小写true,mass_send_all、mass_send_by_tag、mass_send_by_openids、preview_mass_message才注册;前三者还必须传非空clientmsgid和confirm=true。逐次确认:删除类工具以及客服、模板、订阅通知发送工具必须显式传
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环境变量
变量 | 必填 | 说明 |
| 是 | 公众号 AppID |
| 是 | AppSecret,仅经环境变量注入,不落任何文件 |
| 否 | 显式 HTTP(S) 代理;server 不继承宿主代理环境,适用于固定出口 IP 白名单 |
| 否 |
|
| 否 |
|
典型工作流
发布一篇已排版的文章(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。本项目要求回归测试通过 「红灯验证」:修改行为前先确认对应测试在退化实现下真的失败。
文档
docs/proposal.md —— 设计方案 v1.0(工具清单、安全模型、 错误分层、验收标准)
docs/codex-review.md —— 独立 AI 评审记录
docs/api-verification.md —— 官方接口字段与 依赖版本的查证证据
docs/task-implement-v1.md —— v1 实现任务书 (含 10 条行为契约与测试要求)
docs/proposal-v2.md —— v2 设计契约(47 个新增工具)
docs/task-implement-v2.md —— v2 实现任务书 (含 B13~B24 行为契约)
docs/html-usage.md —— 正文 HTML 使用说明 (校验规则、图片引用、回读验证、错误速查)
docs/usage.html —— 使用手册单页 HTML 版 (浏览器直接打开;内容同 README + 正文 HTML 规则)
License
Available Tools
53 toolsbatch_get_user_infoARead-onlyIdempotent
批量获取用户基本信息。
Inputs: openid_list (required). Returns: object
blacklist_usersC
批量拉黑用户。
Inputs: openid_list (required). Returns: object
check_credentialsARead-onlyIdempotent
验证公众号凭据和 IP 白名单;成功不代表拥有发布权限。
Inputs: no named parameters. Returns: object
count_materialsARead-onlyIdempotent
获取各类型永久素材数量。
Inputs: no named parameters. Returns: object
create_draftA
前置校验后创建一个或多个图文草稿,并自动回读验证。
Inputs: articles (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_draftADestructive
删除草稿;必须显式确认。
Inputs: media_id (required), confirm. Returns: object
delete_mass_messageADestructive
删除群发消息;必须显式确认。
Inputs: msg_id (required), confirm, article_idx. Returns: object
delete_materialADestructive
删除永久素材;必须显式确认。
Inputs: media_id (required), confirm. Returns: object
delete_published_articleADestructive
删除已发表文章或其中一篇;必须显式确认。
Inputs: article_id (required), index, confirm. Returns: object
delete_tagADestructive
删除用户标签;必须显式确认。
Inputs: tag_id (required), confirm. Returns: object
download_temp_mediaARead-onlyIdempotent
获取临时素材;二进制响应写入本机 save_path 且不覆盖。
Inputs: media_id (required), save_path (required). Returns: object
get_autoreply_configARead-onlyIdempotent
获取公众号当前自动回复配置。
Inputs: no named parameters. Returns: object
get_draftBRead-onlyIdempotent
读取草稿的完整 news_item 数组。
Inputs: media_id (required). Returns: object
get_jsapi_ticketBRead-onlyIdempotent
获取 JS-SDK 的 jsapi_ticket。
Inputs: no named parameters. Returns: object
get_mass_statusBRead-onlyIdempotent
查询群发消息发送状态。
Inputs: msg_id (required). Returns: object
get_materialARead-onlyIdempotent
获取永久素材;二进制响应写入本机 save_path 且不覆盖。
Inputs: media_id (required), save_path (required). Returns: object
get_published_articleARead-onlyIdempotent
按 article_id 获取单篇已发表文章。
Inputs: article_id (required). Returns: object
get_publish_statusARead-onlyIdempotent
按 publish_id 查询异步发布状态。
Inputs: publish_id (required). Returns: object
get_server_ipsARead-onlyIdempotent
获取微信服务器回调 IP 列表。
Inputs: no named parameters. Returns: object
get_statistics_reportARead-onlyIdempotent
按 report 获取公众号统计数据,并前置校验日期跨度。
Inputs: report (required), end_date (required), begin_date (required). Returns: object
get_user_ids_by_tagARead-onlyIdempotent
分页获取指定标签下的关注者 OpenID。
Inputs: tag_id (required), next_openid. Returns: object
get_user_infoARead-onlyIdempotent
获取单个用户基本信息。
Inputs: openid (required), lang. Returns: object
list_blacklistARead-onlyIdempotent
分页获取公众号黑名单。
Inputs: next_openid. Returns: object
list_commentsBRead-onlyIdempotent
分页读取已发表文章评论。
Inputs: index (required), msg_data_id (required), begin, count, +1 more. Returns: object
list_draftsBRead-onlyIdempotent
分页列出草稿,并通过 draft/count 附带草稿总数。
Inputs: count, offset. Returns: object
list_materialsARead-onlyIdempotent
分页列出指定类型的永久素材。
Inputs: material_type (required), count, offset. Returns: object
list_publishedARead-onlyIdempotent
分页列出成功发布的文章,用于无状态对账。
Inputs: count, offset. Returns: object
list_tagsARead-onlyIdempotent
列出公众号全部用户标签。
Inputs: no named parameters. Returns: object
list_usersARead-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_messageBDestructive
发送客服消息;必须显式确认。
Inputs: openid (required), message (required), confirm. Returns: object
send_subscribe_messageCDestructive
发送订阅通知;必须显式确认。
Inputs: data (required), openid (required), template_id (required), page, +2 more. Returns: object
send_template_messageCDestructive
发送模板消息;必须显式确认。
Inputs: data (required), openid (required), template_id (required), url, +2 more. Returns: object
tag_usersB
批量为用户添加标签。
Inputs: tag_id (required), openid_list (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
Scored across 53 tools
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.
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.
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.
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
Related MCP Connectors
Hosted WeChat Official Account MCP: draft, layout, stock images, publish to drafts.
Create, schedule, and publish social posts, manage accounts, and read analytics as MCP tools.
Social MCP for ideas, drafts, review, publication approvals, scheduling, and explicit publishing.
Social media MCP: publish, schedule & analyze posts on TikTok, Instagram, YouTube, LinkedIn & X
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables management of WeChat Official Accounts by supporting draft creation, image uploads, and content publishing via the MCP protocol. It provides tools for interacting with the WeChat API, including secure token caching and draft list management.-
- AlicenseAqualityFmaintenanceEnables AI agents to publish articles to WeChat Official Account (微信公众号). Supports image upload, draft creation, and publishing via standardized MCP protocol.51ISC
- FlicenseAqualityCmaintenanceEnables management of WeChat Official Account content, including creating, publishing, and deleting drafts and materials, through MCP tools.526-
- FlicenseAqualityCmaintenanceEnables MCP clients like WorkBuddy to connect to the WeChat Official Account API, supporting connection checks, article bundle validation, image uploads, and draft creation and querying, while leaving publishing to the author.43-