Woocommerce Mcp Server

mcp-server-woocommerce

用于通过 Claude 等 AI 助手管理 WooCommerce 商店的 MCP 服务。提供 101 个工具，涵盖产品、订单、客户、优惠券、配送、税费、Webhook、设置、报告等。

快速开始

1. 获取 WooCommerce API 密钥

在 WordPress 管理后台中：依次选择 WooCommerce > Settings > Advanced > REST API > Add key，并设置 Read/Write 权限。

2. 添加到 AI 工具

无需安装，可直接通过 npx 运行：

{
  "mcpServers": {
    "woocommerce": {
      "command": "npx",
      "args": ["-y", "@amitgurbani/mcp-server-woocommerce"],
      "env": {
        "WORDPRESS_SITE_URL": "https://store.example.com",
        "WOOCOMMERCE_CONSUMER_KEY": "ck_your_key",
        "WOOCOMMERCE_CONSUMER_SECRET": "cs_your_secret"
      }
    }
  }
}

{
  "mcpServers": {
    "woocommerce": {
      "command": "npx",
      "args": ["-y", "@amitgurbani/mcp-server-woocommerce"],
      "env": {
        "WORDPRESS_SITE_URL": "https://store.example.com",
        "WOOCOMMERCE_CONSUMER_KEY": "ck_your_key",
        "WOOCOMMERCE_CONSUMER_SECRET": "cs_your_secret"
      }
    }
  }
}

{
  "mcpServers": {
    "woocommerce": {
      "command": "npx",
      "args": ["-y", "@amitgurbani/mcp-server-woocommerce"],
      "env": {
        "WORDPRESS_SITE_URL": "https://store.example.com",
        "WOOCOMMERCE_CONSUMER_KEY": "ck_your_key",
        "WOOCOMMERCE_CONSUMER_SECRET": "cs_your_secret"
      }
    }
  }
}

4. 开始使用 — 可以向 AI 助手提出如下请求：

“列出所有缺货的产品” “创建一张满 $50 订单可用的 10% 折扣优惠券” “显示本周的销售报告”

功能

• 完整的商店管理 — 对产品、分类、标签、品牌、订单、客户和优惠券执行 CRUD 操作
• 产品分类体系 — 属性、属性词项和变体，支持批量操作
• 配送 — 配送区域、区域配送方式和配送类别
• 税费 — 税率和税种
• Webhook — 创建、管理并监控 Webhook 订阅
• 设置 — 读取和更新商店配置
• 报告 — 销售报告、畅销商品、订单/产品/客户总数
• 媒体管理 — 通过 WordPress REST API 列出、删除并清理孤立媒体
• 令牌优化 — 所有工具均支持 fields 参数，仅返回指定字段，可将响应大小缩减 60-97%
• MCP 资源 — 产品、订单、优惠券、退款和支付网关的架构参考，Agent 可读取以获取上下文
• 引导式提示词 — 用于可变产品设置、订单处理和商品目录概览的多步骤工作流
• 工具注释 — 全部 101 个工具均带有 readOnlyHint、destructiveHint 和 idempotentHint，帮助 Agent 安全运行
• 可操作的错误 — 错误响应包含修复常见问题的指导

安全

此服务连接到正在运行的 WooCommerce 商店。 每项创建、更新和删除操作都会影响真实数据。请谨慎操作，尤其是在生产商店中。

开始前

• 使用具有破坏性的工具前，请备份商店。 可使用 WordPress 备份插件或主机提供的备份功能。
• 先在预发布环境中测试。 将生产商店克隆到预发布环境，并将此服务指向预发布 URL。
• 探索时使用只读模式。 设置 WOOCOMMERCE_MCP_READ_ONLY=true 可阻止所有写入操作 — 仅列表、获取和报告类工具可用。

不可逆操作

大多数删除操作会将项目移至回收站（可恢复）。不过，以下操作是永久性的，无法撤销：

级联影响

有些操作会影响不止正在更改的单个项目：

• 删除属性会将其从所有产品中移除——可变产品可能因此出问题
• 删除属性术语会从所有产品和变体中移除该选项
• 删除配送区域会移除该区域中的所有配送方式和位置
• 批量操作（batch_update_attribute_terms、batch_update_variations）可在单次调用中创建、更新并删除项目

API 密钥权限

为确保最大安全性，请创建仅具有所需权限的 WooCommerce API 密钥：

• 只读浏览：创建仅具有读取权限的密钥
• 全面管理：使用读取/写入权限

可用工具（101）

资源

该服务提供 7 个 MCP 资源，为 AI Agent 提供架构参考和指南：

资源提供只读上下文，Agent 可在发起 API 调用前获取这些内容，以了解 WooCommerce 数据结构。

提示词

5 个引导式工作流提示词，用于编排多步骤操作：

工具注解

每个工具都标注了行为提示，帮助 AI Agent 安全地做出决策：

所有工具还会设置 openWorldHint: false——它们仅与 WooCommerce 交互，不会产生外部副作用。

配置

环境变量

使用 .env 文件

无需内联凭据，可改为指定包含 .env 文件的目录：

{
  "mcpServers": {
    "woocommerce": {
      "command": "npx",
      "args": ["-y", "@amitgurbani/mcp-server-woocommerce"],
      "cwd": "/path/to/your/project"
    }
  }
}

多个商店

使用不同的服务名称，从一个项目管理多个商店：

{
  "mcpServers": {
    "store-a": {
      "command": "npx",
      "args": ["-y", "@amitgurbani/mcp-server-woocommerce"],
      "env": { "WORDPRESS_SITE_URL": "https://store-a.com", "..." }
    },
    "store-b": {
      "command": "npx",
      "args": ["-y", "@amitgurbani/mcp-server-woocommerce"],
      "env": { "WORDPRESS_SITE_URL": "https://store-b.com", "..." }
    }
  }
}

令牌优化

所有工具都支持可选的 fields 参数（逗号分隔），仅返回特定字段：

# Browsing products — just names and prices
fields: "id,name,price"

# Stock check
fields: "id,name,stock_status,stock_quantity"

# Order overview
fields: "id,number,status,total"

这可将响应大小减少 60-97%，让 AI 上下文窗口保持聚焦并降低成本。

开发

git clone https://github.com/AmitGurbani/mcp-server-woocommerce.git
cd mcp-server-woocommerce
pnpm install

pnpm dev               # Watch mode
pnpm build             # Build
pnpm start             # Run directly
pnpm test              # Run unit tests
pnpm test:integration  # Run integration tests (requires Docker)
pnpm test:watch        # Run unit tests in watch mode
pnpm inspector         # Debug with MCP Inspector

集成测试通过 @wordpress/env 在真实的 WordPress 6.9.4 + WooCommerce 10.5.3 实例上运行。前提条件：Docker。运行 pnpm test:integration 时，测试环境会自动启动。

Docker

docker build -t mcp-server-woocommerce .
docker run \
  -e WORDPRESS_SITE_URL=https://store.example.com \
  -e WOOCOMMERCE_CONSUMER_KEY=ck_your_key \
  -e WOOCOMMERCE_CONSUMER_SECRET=cs_your_secret \
  mcp-server-woocommerce

远程 / 移动访问（HTTP 传输）

要通过 Claude 移动端、ChatGPT 或其他远程客户端访问 WooCommerce 工具，请在 HTTP 模式下运行服务：

MCP_TRANSPORT=http MCP_AUTH_TOKEN=your-secret-token node build/index.js

或者使用 Docker：

docker run -p 3000:3000 \
  -e MCP_TRANSPORT=http \
  -e MCP_AUTH_TOKEN=your-secret-token \
  -e WORDPRESS_SITE_URL=https://store.example.com \
  -e WOOCOMMERCE_CONSUMER_KEY=ck_your_key \
  -e WOOCOMMERCE_CONSUMER_SECRET=cs_your_secret \
  mcp-server-woocommerce

必须设置 MCP_AUTH_TOKEN，或者设置 AUTH0_DOMAIN + AUTH0_AUDIENCE + MCP_SERVER_URL。

部署指南：请参阅 docs/DEPLOYMENT.md，了解 Railway（约 $0/月）、Fly.io（支持缩容至零，约 $0/月）和 Docker 部署的分步说明。

Claude Desktop / Code：使用 Bearer 令牌身份验证——在配置中添加服务 URL 和 Authorization: Bearer <token> 标头。

Claude.ai 网页版 / 移动端：需要通过 Auth0（免费套餐）使用 OAuth 2.1。请参阅部署指南了解设置说明。

默认模式仍为 stdio——现有的 npx 用户不受影响。

许可证

MIT

WooCommerce 是 Automattic Inc. 的注册商标。本项目与 Automattic Inc. 无关，未获其认可，也未受其赞助。