内容
# MCP WooCommerce
[](https://python.org)
[](LICENSE)
[](https://modelcontextprotocol.io)
**适用于 WooCommerce 店铺管理的 MCP 服务器。** 让 Claude 直接访问您的店铺 — 列出产品、审核质量问题、更新描述和类别、删除重复产品。 不再需要编写脚本或解析 curl 输出。
---
## 功能
| 工具 | 描述 |
|---|---|
| `list_products` | 列出产品，支持筛选（类别、搜索、状态、分页） |
| `get_product` | 获取产品的完整详细信息：图片、描述、类别、价格 |
| `update_product` | 更新任意字段：标题、描述、价格、类别、图片 |
| `delete_product` | 删除或移至回收站产品 |
| `batch_update_products` | 在单个 API 调用中更新多个产品 |
| `list_categories` | 获取所有类别及其 ID 和别名 |
| `audit_products` | 扫描店铺中的问题：幽灵图片、描述过短、类别错误、价格 0 |
`audit_products` 工具检测：
- 描述少于 100 个字符
- 每产品多于 7 张图片
- 主产品图片是 Printful 幽灵/占位符（无设计可见）
- 价格设置为 0
- 产品无类别
- 类别混淆（例如儿童产品也标记为成人）
---
## 安装
### 使用 uvx（推荐 — 无需安装）
```bash
# 直接从 PyPI 运行
uvx mcp-woocommerce
# 或从 GitHub 运行
uvx --from git+https://github.com/cr0hn/mcp-woocommerce mcp-woocommerce
```
### 使用 uv
```bash
uv tool install mcp-woocommerce
# 或从 GitHub 安装
uv tool install git+https://github.com/cr0hn/mcp-woocommerce
```
### 使用 pip
```bash
pip install mcp-woocommerce
```
---
## 配置
需要三个环境变量：
| 变量 | 描述 | 示例 |
|---|---|---|
| `WOOCOMMERCE_URL` | 店铺的基本 URL | `https://mystore.com` |
| `WOOCOMMERCE_CONSUMER_KEY` | WooCommerce REST API 消费者密钥 | `ck_abc123...` |
| `WOOCOMMERCE_CONSUMER_SECRET` | WooCommerce REST API 消费者密钥 | `cs_xyz789...` |
### 生成 API 密钥
1. 进入 **WooCommerce → 设置 → 高级 → REST API**
2. 点击 **添加密钥**
3. 设置权限为 **读写**
4. 复制消费者密钥和密钥（仅显示一次）
---
## Claude 桌面端设置
添加到您的 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"woocommerce": {
"command": "uvx",
"args": ["mcp-woocommerce"],
"env": {
"WOOCOMMERCE_URL": "https://mystore.com",
"WOOCOMMERCE_CONSUMER_KEY": "ck_...",
"WOOCOMMERCE_CONSUMER_SECRET": "cs_..."
}
}
}
}
```
或在 PyPI 发布之前从 GitHub 运行：
```json
{
"mcpServers": {
"woocommerce": {
"command": "uvx",
"args": ["--from", "git+https://github.com/cr0hn/mcp-woocommerce", "mcp-woocommerce"],
"env": {
"WOOCOMMERCE_URL": "https://mystore.com",
"WOOCOMMERCE_CONSUMER_KEY": "ck_...",
"WOOCOMMERCE_CONSUMER_SECRET": "cs_..."
}
}
}
}
```
### Claude 代码（通过 CLI）
```bash
claude mcp add woocommerce \
--command uvx \
--args mcp-woocommerce \
-e WOOCOMMERCE_URL=https://mystore.com \
-e WOOCOMMERCE_CONSUMER_KEY=ck_... \
-e WOOCOMMERCE_CONSUMER_SECRET=cs_...
```
---
## 工具参考
### `list_products`
```
per_page int 每页产品数（默认 20，最大 100）
page int 页码（默认 1）
search str 搜索词
category_id int 按类别 ID 筛选
status str publish | draft | pending | private | any（默认：publish）
```
返回一个列表，包含 `id`、`name`、`price`、`categories`、`image_count`、`description_length`。
### `get_product`
```
product_id int WooCommerce 产品 ID
```
返回完整的产品详细信息，包括所有图片和完整的描述文本。
### `update_product`
```
product_id int 要更新的产品
name str 新标题
description str 新描述（允许 HTML）
short_description str 新简短描述
regular_price str 新价格，例如“14.00”
status str publish | draft | private
category_ids list[int] 要分配的类别 ID（替换现有类别）
image_ids list[int] 要保留的图片 ID（替换现有列表）
```
仅更新提供的字段。其他字段保持不变。
### `delete_product`
```
product_id int 要删除的产品
force bool True = 永久删除，False = 移至回收站（默认 False）
```
### `batch_update_products`
```
updates list[dict] 每个字典需要 'id' + 要更新的字段
```
示例：
```json
[
{"id": 123, "description": "<p>新文本</p>", "categories": [{"id": 16}]},
{"id": 456, "regular_price": "19.00"}
]
```
### `list_categories`
```
per_page int 返回的最大类别数（默认 100）
```
返回 `id`、`name`、`slug`、`count`、`parent`，每个类别。
### `audit_products`
```
per_page int 每请求审核的产品数（默认 100）
fix_images bool 自动修复：移除幽灵图片，限制在 7 张（默认 False）
fix_categories bool 自动修复：移除禁止的类别混淆（默认 False）
```
返回：
```json
{
"total_products": 40,
"ok": 38,
"with_issues": 2,
"fixes_applied": 0,
"issues": [
{
"id": 123,
"name": "产品名称",
"issues": ["描述太短（45 个字符，最小 100）", "图片太多（22 张，最大 7 张）"]
}
]
}
```
---
## 开发
```bash
git clone https://github.com/cr0hn/mcp-woocommerce
cd mcp-woocommerce
uv sync --all-groups
uv run pytest
```
在本地运行服务器：
```bash
WOOCOMMERCE_URL=https://mystore.com \
WOOCOMMERCE_CONSUMER_KEY=ck_... \
WOOCOMMERCE_CONSUMER_SECRET=cs_... \
uv run mcp-woocommerce
```
---
## 许可证
MIT — 见 [LICENSE](LICENSE)。
