微信公众号 MCP Connector

通过本地 stdio MCP，将 WorkBuddy 等 MCP 客户端连接到微信公众号 API：检查连接、校验文章包、上传图片、创建和查询草稿。创建完成后由作者在公众号后台检查排版并手动发布。

功能

不提供正式发布、群发、删除素材、删除草稿或覆盖已有草稿的工具。

准备条件

• Node.js 20.17 或更高版本（建议使用仍受支持的 LTS 版本）和 npm。

• 支持本地 stdio MCP 的客户端，例如 WorkBuddy。

• 微信公众号 AppID、AppSecret，及当前网络出口 IP 的 API 白名单。

• 对应公众号具有素材上传及草稿接口权限。Token 获取成功并不代表拥有全部接口权限。

密钥重置和管理员验证由账号管理员在微信开发者平台完成。不要将密钥发到聊天、Issue 或 Pull Request。

安装

git clone https://github.com/zhuanghaixin/wechat-official-mcp.git
cd wechat-official-mcp
npm ci
cp .env.example .env
chmod 600 .env

用本地编辑器填写 .env：

WECHAT_APP_ID=your_app_id
WECHAT_APP_SECRET=your_app_secret

.env 根据入口文件所在目录加载，不依赖客户端的工作目录。.env.example 只有占位符，不要将实际凭证填入示例文件。

运行连接检查：

npm run check

成功时会显示 wechat_check_access 和 success: true，并返回凭证剩余有效秒数。

接入 WorkBuddy

自动配置（会备份并保留已有 MCP 项目）：

node configure-workbuddy.mjs

脚本写入 ~/.workbuddy/mcp.json，自动使用当前 Node 和入口文件的绝对路径；若同名连接器已存在则停止，避免覆盖。之后刷新 MCP 或重启 WorkBuddy。

也可以手动合并以下配置。先运行 command -v node 获取 Node 路径，将示例路径替换为真实绝对路径：

{
  "mcpServers": {
    "wechat-official-account": {
      "type": "stdio",
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/wechat-official-mcp/index.mjs"]
    }
  }
}

不要直接覆盖其他连接器。更新 Node 或移动项目后，也要更新启动路径。

在 WorkBuddy 对话中输入：

调用 wechat_check_access，检查微信公众号 API 连接，并展示实际工具返回结果。

文章包格式

文章目录必须位于本项目的父目录之内，包括本项目内的子目录。相对路径以项目父目录为基准；建议传绝对路径。真实路径检查也会限制符号链接，目录外文件不能被上传。

workspace/
├── wechat-official-mcp/
└── my-article/
    ├── metadata.json
    ├── article.html
    ├── cover.jpg
    └── images/
        └── 01.jpg

metadata.json：

{
  "title": "文章标题",
  "author": "作者",
  "summary": "文章摘要",
  "cover": { "file": "cover.jpg" }
}

article.html 使用本地图片相对路径：

<section style="font-size:16px;line-height:1.8;">
  <h2>文章小标题</h2>
  <p>正文内容。</p>
  <img src="./images/01.jpg" alt="配图说明" />
</section>

字段与处理规则：

• 标题读取 title，兼容 recommended_title，最多 64 个字符；作者最多 8 个字符。

• 摘要读取 digest，兼容 summary，超过 120 个字符时截断并提示。

• 封面读取 cover.file，缺省为 cover.png。

• 正文图片从 HTML 的 img src 读取，不依赖 inline_images 字段；不下载远程图片。

• 图片在内存中转为 JPEG 并压缩至 1MB 以下，不改动源文件；透明背景变为白色。

• 移除脚本、外链样式和部分不适用的 HTML 属性。建议使用内联样式；此处理不是通用 HTML 安全净化器，应仅处理可信文章包。

• 正文过长会逐步精简装饰样式并返回警告；仍超过长度限制则停止。微信自身也可能调整排版，需要后台预览。

使用示例

先运行仓库自带的演示包校验（不联网、不上传）：

node validate.mjs

校验自己的文章：

node validate.mjs /absolute/path/to/my-article

在 WorkBuddy 先校验：

调用 wechat_validate_article_bundle，bundle_path 为 /absolute/path/to/my-article，展示校验警告。

确认文章内容后创建草稿：

将 /absolute/path/to/my-article 上传到我的公众号草稿箱，调用 wechat_create_draft_from_bundle，返回 media_id 与核验结果，不正式发布。

然后查询：

调用 wechat_get_draft，media_id 为刚刚返回的草稿 ID。

创建工具会先查询草稿数量确认查询接口可用，再上传正文图片和永久封面素材、调用草稿创建接口，并读回核对标题。素材和创建权限最终以实际接口响应为准。

重试与状态记录

.state/ 保存本地内容哈希、草稿 ID 和创建状态，按账号隔离，默认不提交到 Git。

• 相同文章内容再次调用会复用已有草稿 ID。

• 创建请求发出后若结果未知，会阻止自动重试；先到微信后台核对，避免重复生成。

• 进程异常退出可能留下 .lock 文件。确认没有运行中的请求且已核对远端结果后，再人工处理状态。

• 图片上传中断可能留下素材，不会自动删除。

• 修改文章会生成新哈希和新草稿，不会更新旧草稿。

• 不要把 .state 当作临时缓存随意清除，否则会失去去重记录。

故障排查

开发与测试

npm test

测试使用自带演示文章和模拟微信响应，不依赖个人文章或真实密钥，不创建远程草稿。覆盖凭证检查、错误脱敏、路径限制、multipart 上传、草稿创建流程、内容去重及结果未知时的重试保护。

index.mjs               MCP 工具注册
access.mjs              连接检查
bundle.mjs              文章校验与图片预处理
wechat-api.mjs          微信 API 调用
drafts.mjs             草稿流程与本地状态
check.mjs               真实连接检查客户端
validate.mjs            本地文章校验客户端
configure-workbuddy.mjs  WorkBuddy 配置助手
examples/demo/          无私人内容的演示文章包

凭证与仓库内容

仓库仅包含源码、锁文件、测试、演示包与文档。不要提交 .env、.state/、本地 MCP 配置、真实文章素材、日志或配置备份；也不要使用 git add -f 绕过忽略规则。

参考

• MCP TypeScript SDK

• WorkBuddy 连接器

• 微信开发者平台