wechat-oa-mcp-direct

微信公众号 MCP 服务器 —— 直连微信官方 API 版。

基于 FastMCP 4.x 实现，提供公众号草稿创建 / 发布 / 删除、永久素材删除、access_token 获取共 5 个 MCP 工具。所有请求直连 api.weixin.qq.com，不经过任何第三方中转服务器，AppID / AppSecret 只在部署机与微信之间传输。

与 PyPI 上的 wechat-oa-mcp 0.1.0 的区别：旧版会把你的 AppSecret 转发到作者的服务器（106.15.125.133）中转，且依赖已废弃的 MCP SDK v1 API，无法在新环境启动。本包修复了上述问题（含 41001 access_token missing 修复）。

⚠️ 部署前必读：IP 白名单（最容易踩的坑）

部署好后首次调用工具，如果返回 40164 invalid ip ... not in whitelist —— 不是代码问题，是这台部署机的公网出口 IP 还没有加进公众号的 IP 白名单。

• 每台部署机器都要把「它自己的出口 IP」加进白名单（不同机器的 IP 不一样）；
• 换网络、换服务器、IP 变化后都要重新加，否则之前能用的机器会突然报 40164；
• 获取出口 IP 和配置方法见下文「2.2 配置 IP 白名单」。

1. 安装

Windows CMD 一键安装（最简便，无需虚拟环境）

解压 zip 后，在 CMD 中进入解压出来的目录，一条命令安装：

cd wechat-oa-mcp-direct
pip install .

安装完成后验证：

wechat-oa-mcp --help

macOS / Linux，或需要环境隔离时

cd wechat-oa-mcp-direct
python3 -m venv .venv
source .venv/bin/activate        # Windows 虚拟环境: .venv\Scripts\activate
pip install .

要求：Python >= 3.10（Windows 安装 Python 时记得勾选 "Add Python to PATH"，否则 CMD 里 pip 会提示找不到命令）。

2. 前置配置（部署机必须完成）

2.1 获取公众号凭证（AppID / AppSecret 在哪里）

1. 用管理员微信扫码登录微信公众平台：https://mp.weixin.qq.com（需要先注册一个公众号，订阅号/服务号均可）；
2. 左侧菜单点 「设置与开发」→「基本配置」；
3. 页面上的 开发者ID(AppID) 就是 AppID；
4. 开发者密码(AppSecret) 点击「重置」后生成——只会完整显示这一次，请立刻复制保存；之后忘记只能再点「重置」（需管理员扫码确认），且重置后旧 AppSecret 立即失效。

2.2 配置 IP 白名单（关键，编辑位置在这里）

1. 登录微信公众平台：https://mp.weixin.qq.com；
2. 左侧菜单点 「设置与开发」→「开发接口管理」；
3. 找到 「IP白名单」 栏目，点右侧的 「修改」；
4. 输入 部署本服务器那台机器的公网出口 IP（可填多个，用逗号分隔），点 「确认修改」 保存。

如何获取部署机的出口 IP：在部署机的 CMD / 终端执行

curl "https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=你的AppID&secret=你的AppSecret"

若返回 40164 invalid ip <你的IP> not in whitelist，尖括号里的 IP 就是要填进白名单的那个；填好后再执行一次，直到返回 access_token 即配置成功。

⚠️ 出口 IP 可能随网络环境变化（如家庭宽带重拨、换服务器），换网络后必须重新加白名单。

3. 启动服务器

# 默认 SSE 协议，端口 8000（交互式终端）
wechat-oa-mcp
# 或
python -m wechat_oa_mcp

# 指定端口 / 协议 / 调试模式
wechat-oa-mcp --port 8123
wechat-oa-mcp --transport stdio        # stdio 模式（客户端自行拉起时自动生效）
wechat-oa-mcp --debug

⚠️ 后台 / 服务化部署（nohup、systemd、launchd 等）必须显式加 --transport sse：

nohup wechat-oa-mcp --transport sse --port 8000 > mcp.log 2>&1 &

因为非终端环境下程序无法区分「后台运行」与「被 MCP 客户端以管道拉起」，未显式指定协议时默认走 stdio（供 npx inspector / 客户端拉起使用），此时不会监听端口。

启动后 SSE 端点：http://localhost:8000/sse

4. 接入 MCP 客户端

SSE 方式（需服务器保持运行）

{
  "mcpServers": {
    "wechat_oa_mcp": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

stdio 方式（客户端自动拉起，推荐）

{
  "mcpServers": {
    "wechat_oa_mcp": {
      "type": "stdio",
      "command": "wechat-oa-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

若 command 用虚拟环境安装，请填 venv 内的绝对路径，如 /path/to/.venv/bin/wechat-oa-mcp。

5. 可用工具

调用顺序：先 WeChat_get_access_token 拿 token，再调其余工具（token 2 小时内有效）。

注意：WeChat_create_draft 会真实上传图片并在公众号后台创建草稿，属真实写操作，建议先在测试号或测试内容上验证。

6. 常见错误

7. 验证安装

# 检查命令可用
wechat-oa-mcp --help

# 无副作用验证（不创建任何资源）：
# 用 MCP Inspector 或客户端调用 WeChat_get_access_token，成功即说明配置就绪
npx @modelcontextprotocol/inspector python -m wechat_oa_mcp

免责声明

本工具仅限研究用途，禁止用于商业目的。使用者需自行遵守微信公众平台服务条款。