Woocommerce MCP Server

woocommerce-mcp-server

面向 WooCommerce 的生产级模型上下文协议（MCP）服务 — 使用 Claude AI 或任何兼容 MCP 的客户端管理订单、产品、客户、库存和分析数据。

---

🎥 可以做什么

连接后，只需自然地与 Claude 对话：

“显示本周所有正在处理的订单” “哪些产品的库存快用完了？” “查找 SKU 为 WOO-1234 的产品” “我本月的营收是多少？” “哪些客户是最新注册的？” “将订单 #501 标记为已完成”

无需再在 WooCommerce 控制面板中逐个点击。交给你的 AI 处理即可。

---

✨ 功能

• ✅ 20 个可用于生产环境的工具，涵盖订单、产品、客户和分析
• ✅ TypeScript — 完整类型支持，不会出现运行时意外
• ✅ 重试逻辑 — 网络错误和速率限制时自动重试
• ✅ 有意义的错误消息 — 不会向用户抛出原始 API 错误
• ✅ 通过 Zod 验证输入 — 在请求发送至 API 前拒绝无效输入
• ✅ 兼容 Claude Desktop、MCP Inspector 和任何兼容 MCP 的客户端
• ✅ 可通过 npm 安装 — 无需克隆

---

🛠️ 工具参考

📦 订单（5 个工具）

工具	描述
list_orders	按条件筛选订单（状态、日期、客户）
get_order	单个订单的完整详情
update_order_status	更改订单状态 + 可选备注
get_order_notes	订单的所有备注
add_order_note	添加内部备注或客户可见的备注

🏷️ 产品（7 个工具）

工具	描述
list_products	按条件筛选并浏览商品目录
get_product	单个产品的完整详情
update_product	更新价格、库存、状态和描述
get_low_stock_products	库存量低于或达到阈值的产品
get_out_of_stock_products	所有缺货产品
search_products_by_sku	按确切 SKU 查找产品
list_product_categories	所有分类及其数量

👥 客户（4 个工具）

工具	描述
list_customers	浏览并搜索客户
get_customer	完整的客户资料
get_customer_orders	某位客户的所有订单
get_recent_customers	过去 N 天内的新客户

📊 分析（4 个工具）

工具	描述
get_revenue_summary	按周期统计销售额、订单数和平均订单金额
get_sales_report	包含税费、运费和退款的详细报告
get_top_selling_products	按销量排列的畅销产品
get_order_status_counts	按状态统计订单数量

---

🚀 快速设置

前提条件

• Node.js 18+
• 可访问 REST API 的 WooCommerce 商店
• Claude Desktop（用于 AI 集成）

第 1 步 — 生成 WooCommerce API 密钥

1. 前往 WordPress 控制面板
2. 导航至 WooCommerce → 设置 → 高级 → REST API
3. 点击 添加密钥
4. 设置描述：MCP Server
5. 设置权限：读/写
6. 点击 生成 API 密钥
7. 复制你的 Consumer Key 和 Consumer Secret

步骤 2 — 通过 npx 安装（推荐）

无需安装。直接配置 Claude Desktop：

打开 Claude Desktop 配置文件：

• Windows： C:\Users\<YourName>\AppData\Roaming\Claude\claude_desktop_config.json
• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

添加以下配置：

{
  "mcpServers": {
    "woocommerce": {
      "command": "npx",
      "args": ["-y", "woocommerce-mcp-server"],
      "env": {
        "WOOCOMMERCE_URL": "https://yourstore.com",
        "WOOCOMMERCE_CONSUMER_KEY": "ck_your_consumer_key_here",
        "WOOCOMMERCE_CONSUMER_SECRET": "cs_your_consumer_secret_here"
      }
    }
  }
}

重启 Claude Desktop。你应该会看到一个 🔌 插头图标——现在你的 WooCommerce 商店已连接。

---

其他方式 — 克隆并在本地运行

git clone https://github.com/arbazex/woocommerce-mcp-server.git
cd woocommerce-mcp-server
npm install

创建 .env 文件：

WOOCOMMERCE_URL=https://yourstore.com
WOOCOMMERCE_CONSUMER_KEY=ck_your_key_here
WOOCOMMERCE_CONSUMER_SECRET=cs_your_secret_here

构建并运行：

npm run build
node build/index.js

然后更新 Claude Desktop 配置，使其指向本地构建：

{
  "mcpServers": {
    "woocommerce": {
      "command": "node",
      "args": ["C:\\path\\to\\woocommerce-mcp-server\\build\\index.js"],
      "env": {
        "WOOCOMMERCE_URL": "https://yourstore.com",
        "WOOCOMMERCE_CONSUMER_KEY": "ck_your_key_here",
        "WOOCOMMERCE_CONSUMER_SECRET": "cs_your_secret_here"
      }
    }
  }
}

---

🧪 使用 MCP Inspector 进行测试

在浏览器中测试工具，无需使用 Claude Desktop：

npx @modelcontextprotocol/inspector build/index.js

先设置环境变量：

# Windows PowerShell
$env:WOOCOMMERCE_URL="https://yourstore.com"
$env:WOOCOMMERCE_CONSUMER_KEY="ck_your_key"
$env:WOOCOMMERCE_CONSUMER_SECRET="cs_your_secret"

# macOS/Linux
export WOOCOMMERCE_URL="https://yourstore.com"
export WOOCOMMERCE_CONSUMER_KEY="ck_your_key"
export WOOCOMMERCE_CONSUMER_SECRET="cs_your_secret"

---

🔑 API 密钥权限

功能	所需权限
读取订单、商品、客户、分析数据	读取
更新订单状态、添加备注、更新商品	读取/写入

⚠️ 如果没有写入权限，更新工具将返回身份验证错误。请生成一个具有读取/写入权限的密钥，以使用全部功能。

---

📁 项目结构

woocommerce-mcp-server/
├── src/
│   ├── index.ts          # Entry point (stdio transport)
│   ├── server.ts         # MCP server setup
│   ├── woo-client.ts     # WooCommerce API client (retry + error handling)
│   ├── types/
│   │   └── woo-types.ts  # Full TypeScript type definitions
│   └── tools/
│       ├── orders.ts     # Order management tools
│       ├── products.ts   # Product management tools
│       ├── customers.ts  # Customer management tools
│       └── analytics.ts  # Reporting and analytics tools
├── build/                # Compiled output (generated)
├── package.json
├── tsconfig.json
└── .env.example

---

🔒 安全

• API 凭据通过环境变量传递——绝不硬编码
• 所有输入在调用 API 前都会使用 Zod 进行验证
• 通过自动重试 + 退避妥善处理速率限制错误
• 不会将凭据记录到 stdout（仅调试消息会记录到 stderr）

---

🛠️ 开发

# Install dependencies
npm install

# Watch mode (auto-rebuild on save)
npm run dev

# Build once
npm run build

# Open MCP Inspector
npm run inspect

---

🤝 贡献

欢迎贡献！如果你对新工具有想法或发现了 bug：

1. Fork 此仓库
2. 创建分支：git checkout -b feature/your-tool-name
3. 进行修改
4. 发起 Pull Request

---

📋 路线图

• 创建订单工具
• 优惠券管理工具
• Webhook 管理
• 支持商品变体
• 用于托管部署的远程 HTTP（Streamable HTTP）传输
• 支持批量操作

---

📄 许可证

MIT © Arbaz

---

由 Arbaz 倾心打造 ❤️