Metadata-Version: 2.4
Name: wechat-oa-mcp-direct
Version: 0.2.0
Summary: 微信公众号 MCP 服务器（直连微信官方 API 版）：草稿创建/发布/删除、素材删除、access_token 获取
Author-email: Jupiter <jupiter3019@163.com>
License: MIT
Keywords: wechat,mcp,fastmcp,公众号
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=4.0
Requires-Dist: requests>=2.25

# 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 中进入解压出来的目录，一条命令安装：

```cmd
cd wechat-oa-mcp-direct
pip install .
```

安装完成后验证：

```cmd
wechat-oa-mcp --help
```

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

```bash
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 / 终端执行
> ```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. 启动服务器

```bash
# 默认 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`**：
> ```bash
> nohup wechat-oa-mcp --transport sse --port 8000 > mcp.log 2>&1 &
> ```
> 因为非终端环境下程序无法区分「后台运行」与「被 MCP 客户端以管道拉起」，未显式指定协议时默认走 stdio（供 npx inspector / 客户端拉起使用），此时不会监听端口。

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

## 4. 接入 MCP 客户端

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

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

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

```json
{
  "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` | AppID, AppSecret | 获取 access_token（有效期 7200 秒） |
| `WeChat_create_draft` | access_token, image_url, title, content | 下载封面图→上传永久素材→创建图文草稿；可选 author / digest / content_source_url / need_open_comment |
| `WeChat_publish_draft` | access_token, draft_media_id | 发布草稿（异步任务，返回 publish_id） |
| `WeChat_del_draft` | access_token, media_id | 删除草稿 |
| `WeChat_del_material` | access_token, media_id | 删除永久素材 |

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

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

## 6. 常见错误

| 错误码 | 含义 | 处理 |
|---|---|---|
| 40164 | IP 不在白名单 | 把部署机出口 IP 加入公众号 IP 白名单 |
| 41001 | access_token missing / invalid | 确认已先调用 get_access_token 且 token 未过期 |
| 40007 | invalid media_id | media_id 不存在或已删除 |
| 45009 | 接口调用超限 | 微信接口有频率限制，稍后重试 |

## 7. 验证安装

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

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

## 免责声明

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