xwang152-jack/wechat-official-account-mcp

Developer tools

67 stars 26 forks Quality 86 Trend 28MIT

Repository Install

为 AI 应用（Claude Desktop、Cursor 等）提供微信公众号 API 集成的 MCP 服务。

Overview

为 AI 应用（Claude Desktop、Cursor 等）提供微信公众号 API 集成的 MCP 服务。

README

微信公众号 MCP 服务

为 AI 应用（Claude Desktop、Cursor 等）提供微信公众号 API 集成的 MCP 服务。

当前版本: v2.2.1 · 更新日志 · 开发者指南

运行时: Node.js 20.17+
协议: MCP (Model Context Protocol) · 存储: SQLite · 语言: TypeScript

快速开始

WECHAT_APP_ID= WECHAT_APP_SECRET= npx wechat-official-account-mcp mcp

接入 Claude Desktop，在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "wechat-official-account": {
      "command": "npx",
      "args": ["wechat-official-account-mcp", "mcp"],
      "env": {
        "WECHAT_APP_ID": "",
        "WECHAT_APP_SECRET": ""
      }
    }
  }
}

推荐用环境变量而非 -a/-s 参数传 AppSecret，避免密钥出现在进程命令行里。

凭据会存入 ./data/wechat-mcp.db，其中 app_secret 等敏感字段默认 AES 加密（密钥未指定时自动生成于 ./data/.secret-key，权限 600）。

工具

对外暴露 14 个工具，按「读写分离」组织：只读与写入操作位于不同工具，便于客户端对写入操作做权限控制。所有工具返回 JSON。

类别	工具
内容	`wechat_content_read` / `wechat_content_write` — 草稿与发布
素材	`wechat_media_read` / `wechat_media_write` — 永久/临时素材、图文内图片
用户	`wechat_audience_read` / `wechat_audience_write` — 粉丝、标签、黑名单
互动	`wechat_engagement_read` / `wechat_engagement_write` — 文章评论
消息	`wechat_messaging_read` / `wechat_messaging_write` — 模板/客服/订阅/群发
数据	`wechat_statistics` — 发表内容、消息、接口统计（只读）
长尾	`search_actions` + `execute_read_action` / `execute_write_action`

每个域工具用一个 action 参数选择具体操作，例如：

wechat_content_read  { "action": "list", "count": 10 }     # 列出草稿
wechat_content_write { "action": "add", "articles": [...] } # 新建草稿
wechat_content_write { "action": "submit", "mediaId": "..." } # 提交发布

菜单、二维码、短链、客服账号、账号配额、自动回复、商品卡片、认证配置等长尾能力未单独建工具，先用 search_actions 检索动作 ID（共 101 个），再用 execute_read_action / execute_write_action 执行。服务端 instructions 已说明该用法。

配置

环境变量	说明
`WECHAT_APP_ID` / `WECHAT_APP_SECRET`	公众号凭据（也可用 `-a` / `-s`）
`WECHAT_MCP_SECRET_KEY`	敏感字段加密密钥；未设置时自动生成本地密钥
`WECHAT_MCP_SECRET_KEY_FILE`	本地密钥文件路径，默认 `./data/.secret-key`
`DB_PATH`	数据库路径，默认 `./data/wechat-mcp.db`
`MCP_HTTP_TOKEN`	HTTP 模式下的 Bearer 鉴权令牌
`CORS_ORIGIN`	HTTP 模式下的来源白名单（逗号分隔）
`DEBUG`	开启调试日志

AppID / AppSecret 获取：微信公众平台 → 开发 → 基本配置。

远程部署（Streamable HTTP）

MCP_HTTP_TOKEN=$(openssl rand -hex 32) \
CORS_ORIGIN=https://your-client.example \
npx wechat-official-account-mcp mcp -m http -p 3000

端点	说明
`POST /mcp`	MCP 端点（无状态）
`GET /healthz`	探活，不鉴权

⚠️ 微信 IP 白名单：公众号 API 要求调用方 IP 在账号后台白名单内，否则报 40164 invalid ip。部署到服务器后，需把该服务器出口 IP 加入「公众号后台 → 开发 → 基本配置 → IP 白名单」。

--mode sse 保留但已废弃（该传输无鉴权且被 MCP 规范取代），建议改用 http。

也可以直接用 Docker：docker compose up -d（见 docker-compose.yml）。 systemd + nginx 常驻部署的配置与运维步骤与环境强相关，不入库，保存在本地 deploy/。

开发

npm install
npm run dev -- mcp -a  -s    # 开发模式
npm run check && npm run lint && npm test         # 静态检查与测试
npm run verify                                    # 端到端校验（协议层 / 字段映射 / HTTP 鉴权）
npm run build                                     # 构建到 dist/

相关文档：CHANGELOG · CLAUDE.md（架构与开发规范）· 微信官方文档 · MCP 规范

安全

凭据加密：app_secret / access_token / encoding_aes_key 默认 AES 加密落库（enc: 前缀）；日志对敏感字段脱敏
HTTP 鉴权：--mode http 下设置 MCP_HTTP_TOKEN 后所有 /mcp 请求需带 Authorization: Bearer，未设置时启动即告警
CORS：仅接受 CORS_ORIGIN 白名单内的来源，不使用通配符
输入校验：全部工具经 Zod schema 运行时校验，HTML 内容经 sanitizeHtmlContent() 清理
凭据不外泄：wechat_auth 的返回只含 appId 与布尔标记，不返回任何密钥或令牌

许可证

MIT · 作者 xwang152-jack <[email protected]>

View the full README on GitHub

Install

npx wechat-official-account-mcp mcp

New to MCP? Start with the mcpskill.org guide →

Configuration

{
  "mcpServers": {
    "wechat-official-account": {
      "command": "npx",
      "args": ["wechat-official-account-mcp", "mcp"],
      "env": {
        "WECHAT_APP_ID": "<your_app_id>",
        "WECHAT_APP_SECRET": "<your_app_secret>"
      }
    }
  }
}