内容
# woocommerce-mcp
一个适用于 **WordPress + WooCommerce** 的小型只读 [模型上下文协议](https://modelcontextprotocol.io) 服务器。它允许 Claude（或任何 MCP 客户端）通过官方 REST API 查询实时商店中的产品、订单、销售和博客帖子。无需写入，无需在商店中安装插件：它直接与现有的 WordPress/WooCommerce REST 端点通信。
由 [WPPoland](https://wppoland.com/en/) 构建和维护——高级 WordPress & WooCommerce 工程团队。如果您需要将此功能集成到实际的商店栈中，我们提供 [WooCommerce ERP 和 API 集成](https://wppoland.com/en/woocommerce-erp-integration/) 和 [企业电子商务架构](https://wppoland.com/en/enterprise-solutions/)（无头、集成、AI-ready 数据）。
## 工具列表
| 工具 | 功能 | 需要 WooCommerce 密钥 |
|------|--------------|:---:|
| `list_products` | 列出/搜索产品（名称，sku，价格，库存，永久链接） | 是 |
| `get_product` | 通过 ID 获取一个产品的完整详细信息 | 是 |
| `list_orders` | 最近的订单，新建的优先，可选状态过滤 | 是 |
| `sales_report` | 指定期间的销售总额（周/月/上月/年） | 是 |
| `search_posts` | 搜索已发布的博客帖子（公共 WP REST API） | 否 |
所有操作均为**只读**。服务器永远不会在商店中创建、编辑或删除任何内容。
## 安装与构建
```bash
git clone https://github.com/wppoland/woocommerce-mcp.git
cd woocommerce-mcp
npm install
npm run build
```
## 配置
设置三个环境变量：
| 变量 | 是否必需 | 示例 |
|-----|:---:|---------|
| `WP_URL` | 是 | `https://shop.example.com` |
| `WC_CONSUMER_KEY` | 用于 `wc_*` 工具 | `ck_xxx` |
| `WC_CONSUMER_SECRET` | 用于 `wc_*` 工具 | `cs_xxx` |
在 **WooCommerce → 设置 → 高级 → REST API → 添加密钥** 中创建 WooCommerce 密钥，并赋予 **读取** 权限。`search_posts` 无需密钥即可在任何公共 WordPress 站点上工作。
> 密钥通过 HTTPS 作为 REST 查询身份验证发送到您的商店。请使用 HTTPS，并仅授予密钥 **读取** 访问权限。
## 与 Claude Desktop / Claude Code 一起使用
将以下内容添加到您的 MCP 客户端配置文件（例如 `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"woocommerce": {
"command": "node",
"args": ["/absolute/path/to/woocommerce-mcp/dist/index.js"],
"env": {
"WP_URL": "https://shop.example.com",
"WC_CONSUMER_KEY": "ck_xxx",
"WC_CONSUMER_SECRET": "cs_xxx"
}
}
}
}
```
然后询问类似 *"上个月的 WooCommerce 销售情况如何？"* 或 *"列出 5 个最近处于暂停状态的订单。"*
## 验证
```bash
npm run check # 构建，然后断言所有五个工具已注册（无需网络/凭证）
```
## 注意事项
- Node 18+（使用内置的 `fetch`）。
- 日志输出到 stderr，因此它们永远不会破坏 stdout 上的 stdio MCP 协议。
- API 错误会显示商店的消息；凭证永远不会被回显。
## 许可证
MIT © [WPPoland](https://wppoland.com/en/)
