igorwang/wechat-oap-api
igorwang/wechat-oap-api has 241 GitHub stars and 25 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-19 03:17 UTC. Last push 2026-11-09.
Measured star growth
- in 24h
- 0
- in 7 days
- Collecting history
- in 15 days
- Collecting history
- in 1 month
- Collecting history
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
微信公众号(订阅号 / 服务号)服务端 API 的 FastAPI 封装,同时通过 MCP 对 AI Agent 暴露。 Token 自动缓存、鉴权内置、一条 docker compose up 即可部署。
Developer ToolsREADME.md
Originalwechat-oap-api
微信公众号(订阅号 / 服务号)服务端 API 的 FastAPI 封装,同时通过 MCP 对 AI Agent 暴露。
Token 自动缓存、鉴权内置、一条 docker compose up 即可部署。
- HTTP 接口覆盖基础能力、发布、草稿、素材、文章运营统计、消息,以及微信客服与回调
- Access Token 自动管理:内部使用稳定版 Token,asyncio 锁去重 + 文件持久化 + 40001/42001 一次恢复重试
- MCP 共 24 个工具:草稿、素材、healthz,加上已发表文章列表/正文查询与四个只读运营统计工具。正式发布、删除已发表文章、群发和订阅消息保留为 HTTP-only。见
main.py的MCP_TOOLS白名单 - API Key 鉴权:保护
/wechat/*与/mcp,可关 - 离线测试:httpx + respx + pytest-asyncio;运行结果以本次检查为准
服务端安装
需要:python >= 3.13 或 Docker。
方式一:本地 uv 运行(开发)
cp .env.example .env # 填 WECHAT_APPID / WECHAT_APPSECRET
uv sync
uv run uvicorn main:app --reload
访问 http://127.0.0.1:8000/docs 查看所有接口。
方式二:Docker Compose(推荐部署)
Compose 直接消费 Docker Hub 上已发布的 multi-arch 镜像 igorwang/wechat-oap-api(linux/amd64 + linux/arm64),不做本地构建:
cp .env.example .env # 填 WECHAT_APPID / WECHAT_APPSECRET / API_KEY
docker compose pull # 拉最新镜像(本机架构自动匹配)
docker compose up -d
docker compose logs -f api
- 端口默认
:8000,用.env的PORT可改 - Token 缓存挂载到
token-cachevolume,容器重启不会重新申请 - Healthcheck 每 30s 打
/healthz,docker compose ps能看到healthy状态 - 固定版本:
IMAGE_TAG=0.1.0 docker compose up -d
构建并发布新镜像(仅维护者)
docker login -u igorwang # 需要写权限的 Docker Hub 账号
scripts/docker-push.sh # 读 pyproject.toml 的 version,打 :latest + :$version
scripts/docker-push.sh v0.2.0 # 或手动指定 tag
脚本用 docker buildx --platform linux/amd64,linux/arm64 一次构建两架构并直接 push。
环境变量
| 变量 | 必填 | 默认 | 说明 |
|---|---|---|---|
WECHAT_APPID |
✓ | — | 公众号 AppID |
WECHAT_APPSECRET |
✓ | — | 公众号 AppSecret |
WECHAT_API_BASE |
https://api.weixin.qq.com |
||
WECHAT_TOKEN_CACHE_PATH |
.wechat_token.json |
置空禁用磁盘缓存 | |
API_KEY |
"" |
保护 /wechat/* 与 /mcp,置空 = 关闭鉴权(本地开发) |
|
API_KEY_HEADER |
X-API-Key |
鉴权 header 名 | |
PORT |
8000 |
compose 对外映射端口 |
AppID、AppSecret、IP 白名单和接口权限在微信开发者平台管理,入口以官方迁移说明为准。
Feyn OS 微信客服
- 「进群」默认发送镜像内置的 Feyn OS 公开群二维码,无需额外配置。换码时更新这张图并重新打镜像。
- 如需不重打镜像就换码:把图片放到宿主机
data/customer-service/group.png(容器用户 UID 10001 可读),设置CS_GROUP_QR_PATH=/data/customer-service/group.png。之后替换该文件即可,无需重启。 - 用普通微信账号打开客服会话,发送「产品」查看介绍,再发送「进群」并长按收到的码,确认进入目标群。「加群」「加入群聊」也会发码。固定指令无需关注公众号,也不占 AI 聊天额度。
公众号文章用的 Feyn OS 公开群二维码 随镜像发布,路径为 /static/feyn-group-qrcode.png,可直接下载。写文章时可复用微信正文图片,或用 bash skills/wechat-api/scripts/wechat.sh upload-inline app/static/feyn-group-qrcode.png 取得微信图片地址。换码时同步更新仓库图片并重新上传正文素材。已发表文章中的二维码仍是发表时的图片。
客服直接回复 Feyn OS 知识库 中命中的常见问题,模型也参考同一份知识库回答其他问法。改动知识库后,重启新版本以载入内容。AI 问答按客户 ID 每天最多处理 50 条消息,按北京时间零点重置。额度保存在数据库中,数据库不可用时固定回复仍可使用,AI 问答暂停。模型继续通过 DEEPSEEK_MODEL、DEEPSEEK_API_BASE 和 DEEPSEEK_API_KEY 配置。
稳定凭据与永久素材下载
内部缓存默认调用 POST /cgi-bin/stable_token,普通获取使用 force_refresh=false,过期时间使用响应的 expires_in。收到 40001/42001 时,仅在被拒绝的 Token 仍为当前缓存时强制刷新,并重试原请求一次;并发的旧请求复用已刷新的 Token。手动调用 /wechat/stable-token 也会同步业务缓存。
持久化缓存带 token_source: stable_token;升级后忽略无此标记的旧缓存,首次业务请求重新获取稳定凭据。继续使用已有 AppID、AppSecret 和缓存路径。
POST /wechat/material/permanent/get 返回图文、视频及微信错误时仍为 JSON。图片、语音等二进制素材默认返回 MCP 可读取的对象:
{"encoding": "base64", "content_type": "image/png", "data": "<Base64 文件内容>"}
HTTP 下载原始文件时,在同一接口添加查询参数 ?response_format=raw,请求体仍为 {"media_id": "永久素材ID"};响应保留原始字节、Content-Type 和上游 HTTP 状态。MCP 调用使用默认值或显式 response_format=base64,将 data 做 Base64 解码即可还原文件。
实现与本轮验证见稳定 Token 与素材下载维护记录。
鉴权
启用鉴权只需在 .env 设 API_KEY=some-long-random-string,随后所有 /wechat/* 和 /mcp 请求必须带 header:
X-API-Key: some-long-random-string
放行路径(不需要 key):/healthz, /docs, /redoc, /openapi.json, /static/*。
服务端 API_KEY 与客户端 WECHAT_API_KEY 使用同一个值:服务端负责校验,客户端脚本和 MCP 负责发送。WECHAT_OAP_API_KEY 是旧客户端变量名;新配置统一使用 WECHAT_API_KEY。HTTP 脚本仍支持旧名回退,两者同时设置时以新名为准。原先仅导出旧变量的 MCP 客户端,请将相同值迁到 WECHAT_API_KEY,再重载配置。
接入 Claude Code(MCP 客户端)
核心思路:API Key 配在 MCP 客户端侧一次,之后任何 skill / prompt / subagent 调用工具都不用感知 key。这样:
- Skill 代码里不会出现 secret
- 同一机器上多个 agent 共享同一套 MCP 配置
- 轮换 key 只改一处
方式 A(推荐):项目级 .mcp.json
本仓库已附带 .mcp.json:
{
"mcpServers": {
"wechat-oap": {
"type": "http",
"url": "http://localhost:8000/mcp",
"headers": {
"X-API-Key": "${WECHAT_API_KEY}"
}
}
}
}
使用步骤:
- 本地/服务器上把服务跑起来(
docker compose up -d) - 在 shell 里 export key:
export WECHAT_API_KEY=...(建议写进~/.zshrc或 direnv) cd进本仓库,Claude Code 首次会提示"approve project MCP",同意即可claude mcp list能看到wechat-oap
优势:
.mcp.json可安全 commit(只引用 env 变量,不含真 key)- 团队成员 clone 仓库后只需 export 自己的 key 即可
- URL 要改(部署到生产),直接改
.mcp.json并 commit
方式 B:全局 ~/.claude.json(其他项目也想用)
如果多个仓库都想调这套 MCP,写到用户级配置:
{
"mcpServers": {
"wechat-oap": {
"type": "http",
"url": "https://your-production-host/mcp",
"headers": {
"X-API-Key": "real-key-here"
}
}
}
}
方式 C:claude mcp add
claude mcp add \
--transport http \
--header "X-API-Key: your-api-key" \
wechat-oap http://localhost:8000/mcp
验证
进入 Claude Code 后问一句:
用 wechat-oap 检查服务健康状态
Claude 会调用 MCP 工具 healthz。需要验证鉴权时再调用 draft_count;healthz 是公开健康检查,不验证 API Key。Token 查询只通过 HTTP 提供,不在 MCP 白名单内。
安装 wechat-api Skill
本仓库在 skills/wechat-api/ 内置公众号写作、排版与草稿技能。2026-11-04 同步了 SurviAGI 于 2026-11-03 确认的长文语言模板和 v7 视觉标准,配套资源全部位于技能内,可单独安装。
项目级安装(只在当前项目生效):
mkdir -p .claude/skills
npx -y degit igorwang/wechat-oap-api/skills/wechat-api .claude/skills/wechat-api
全局安装(所有项目都能用):
npx -y degit igorwang/wechat-oap-api/skills/wechat-api ~/.claude/skills/wechat-api
安装完成后,在 Claude Code 里输入类似 "帮我起草一篇公众号图文" / "上传一张封面图" 就会自动触发;也可以 /wechat-api 显式调用。
本地写作与排版不需要 MCP 或 API Key。创建/更新远端草稿才需接入自己的服务;图片上传使用技能内 HTTP 脚本。
Skill 怎么用
在技能目录安装依赖,再生成仓库内的演示稿:
cd skills/wechat-api
npm --prefix scripts ci --ignore-scripts
node scripts/render.mjs examples/editorial-article.md --out-dir /tmp/wechat-editorial-preview --date 2026-11-04
需要 Node.js 20+;本地结构检查另需 Python 3。输出 article.wechat.html、article-preview.html,以及 research/article-conversion.json、research/article-layout-check.json。预览仅在本地,命令不会上传或写入草稿。
- 写作模板:四段已认可样例及适用条件,覆盖事件、解释、轻吐槽和故事包袱。
- 视觉模板:固定 C 版 Logo、近黑/绿色层级、透明正文、动态目录、章标和统一署名。仅为其他账号排版时保留其品牌和原文,使用原
md2wechat.mjs通用入口。 - 草稿回读:上传使用本次清单里的全部图片,含品牌图;图片替换后再写入草稿,完成后重新读取核验。
维护时验证:
npm --prefix skills/wechat-api/scripts test
python3 skills/wechat-api/scripts/check.py skills/wechat-api/examples/editorial-article.md
bash skills/wechat-api/scripts/ai-voice-check.sh skills/wechat-api/examples/editorial-article.md
MCP 同时支持只读文章运营,使用方法见技能的文章运营指南。正式发布、群发和订阅消息保留 HTTP 接口,由使用者按自己的授权流程操作。
接口总览
| 分组 | 路由前缀 | operation_id 前缀 | 数量 |
|---|---|---|---|
| 基础接口 | /wechat/{token,stable-token,callback/check,api-domain-ip,callback-ip,clear-quota} |
— | 6 |
| 发布能力 | /wechat/freepublish/* |
freepublish_* |
5 |
| 文章运营 | /wechat/analytics/* |
analytics_* |
4 |
| 草稿管理 | /wechat/draft/* |
draft_* |
8 |
| 素材管理 | /wechat/material/{permanent,temporary}/* |
material_* |
9 |
| 基础消息 | /wechat/message/{mass,subscribe,autoreply}/* |
message_* |
9 |
完整 schema 见 http://localhost:8000/docs 。
文章运营(HTTP 与 MCP)
| HTTP POST 路径 | MCP 工具 | 官方接口/日期口径 |
|---|---|---|
/wechat/analytics/article-read |
analytics_article_read |
getarticleread,单日统计日期,逐篇阅读人数与来源 |
/wechat/analytics/article-share |
analytics_article_share |
getarticleshare,单日统计日期,逐篇分享人数 |
/wechat/analytics/account-summary |
analytics_account_summary |
getbizsummary,统计日期区间,含首尾最多 30 天 |
/wechat/analytics/article-details |
analytics_article_details |
getarticletotaldetail,单日发表日期,含标题、链接和阅读质量 |
请求统一为 {"begin_date":"2026-11-01","end_date":"2026-11-01"}。本地校验日期格式、有效日历、起止顺序、跨度、最早 2025-11-01、最晚北京时间昨日;非法请求返回 422,不调用微信。建议次日 8 点后查询昨日数据。
四个统计接口均要求企业主体已认证账号;新增封装不会改变账号权限。返回微信原始 JSON,保留指标、is_delay(布尔值或文档示例字符串)、空列表及 48001 等错误。阅读/分享为人数;单篇详情 detail_list 是发表日至各统计日的累计,单篇跟踪发表起 30 天,多条累计记录不可相加。
已发表文章列表和正文继续使用 /wechat/freepublish/batchget、/wechat/freepublish/getarticle,现在也通过 MCP 的 freepublish_batchget、freepublish_getarticle 开放查询。它们返回的 article_id 与统计的 msgid、草稿的 media_id 应分别使用。
官方支持范围及来源见统计接口调研。以上为代码支持,服务升级部署和真实账号权限需分别核实。
腾讯 API 核查与兼容
2026-11-04 对照官方文档维护了两处兼容:草稿支持 article_type: newspic,无需传统封面 ID,改用最多 20 张永久图片素材;永久素材列表支持 news 类型。旧图文不填 article_type 时继续按 news 处理,裁切和商品扩展字段保留透传。
官方来源、文档歧义、验证范围与待处理差异见 本次维护记录。这次核查不代表线上服务已升级。
开发
uv sync # 含 dev group
uv run pytest # 离线服务端回归
uv run pytest -v tests/test_auth.py # 单文件
结构:
app/
├── config.py # pydantic-settings, 读 .env
├── wechat.py # WeChatClient: token 缓存 + call_json / call_multipart
├── auth.py # X-API-Key 中间件
└── routers/
├── freepublish.py
├── analytics.py
├── draft.py
├── material.py
└── message.py
main.py # FastAPI app + FastApiMCP 挂载
tests/ # respx mock,不打真微信
License
MIT