WooCommerce MCP

woocommerce-mcp

一个用于通过 WooCommerce REST API 操作一个或多个 WooCommerce 商店的模型上下文协议服务。MCP 客户端可以浏览商品目录、处理和履行订单、发起退款、批量调整价格和库存、开展促销活动、细分客户、响应 Webhook，并查看销售分析。每项更改都会在应用前预览，也可以写入审计日志。

它可通过 stdio 在本地运行，也可通过可流式传输的 HTTP 作为远程服务运行，并支持 bearer token 或 OAuth 2.0 身份验证；此外还以 Docker 镜像的形式发布在 GitHub Container Registry 上。

文档： https://sadrmanesh.github.io/woocommerce-mcp/ · 工具浏览器： Hugging Face Space

延伸阅读： Dev.to 上的面向 Agent 的安全写入工具：在 WooCommerce MCP 服务中预览、确认、审计和处理过期预览 · LinkedIn 上的预览、确认、审计 · 更新：Dev.to 上的一周读者反馈：我的四款 AI 商业工具有哪些变化 · LinkedIn 上的读者反馈让我学到什么：如何构建适用于商业场景、可安全用于生产环境的 AI 工具

该项目已列入官方 MCP Registry，条目为 io.github.sadrmanesh/woocommerce-mcp，也已列入 Glama 和 mcpservers.org。

目录

• 亮点
• 快速开始
• 连接 MCP 客户端
• 工具、资源和提示词
• 安全写入
• 配置
• 部署
• 开发
• 文档

亮点

• 多店铺。 可配置任意数量的店铺，并在每次调用时通过 store 选择一个。每个店铺都有自己的凭据和只读开关。
• 默认安全。 店铺默认为只读，除非你允许写入。之后，写入工具会返回确切 REST 请求的预览；只有再次调用并设置 confirm: true 时才会执行。如果自预览以来参数或用于计算变更的店铺数据发生变化，确认将被拒绝。dryRun: true 始终只生成预览。
• 签名审批（可选）。 设置 WOOCOMMERCE_APPROVAL_SECRET 后，确认操作还需要一个短时有效、仅可使用一次的令牌。该令牌必须由 Agent 无法触及的人员针对该预览准确签名，例如使用 woocommerce-mcp approve <previewId> 进行签名。Agent 不能批准自己的写入操作。
• 审计日志。 每次写入尝试记录一行 JSON：已执行、已预览、已拒绝或失败，并包含工具、店铺、参数、调用方以及预览 ID；每项已确认的写入都可通过该 ID关联到对应预览。
• 退款和批量操作。 支持部分退款和按商品行退款、最多更新 100 个产品的批量操作，以及百分比或固定金额调价。
• 分析。 按日、周或月统计销售额，包含退款、平均订单金额、热销产品和付款方式；还提供涵盖变体商品的低库存报告。
• 促销和客户。 提供优惠券效果、定时促销，以及 VIP、回头客和高风险等客户细分。
• 履约。 支持订单备注、配送跟踪，以及通过单个步骤完成履约并向客户发送邮件。
• Webhooks。 管理店铺 Webhooks 并接收签名投递内容，可通过 MCP 资源读取。
• 配送和税费。 读取配送区域、配送方式、税率和税类。
• 隐私与控制。 可选的个人身份信息（PII）脱敏功能，以及按部署或店铺设置工具允许列表和拒绝列表。
• 降低店铺负担。 按店铺限流、使用退避和抖动机制重试，并可选择启用读取缓存。
• 支持远程部署。 支持 Streamable HTTP，可使用静态 bearer 令牌（完全权限或只读权限），或 RFC 7662 令牌内省；支持 RFC 9728 受保护资源元数据、Host 和 Origin 检查，以及健康检查端点。
• MCP 资源和提示词。 通过 URI 读取产品和订单，并启动常见工作流，例如销售简报或补货计划。
• 可观测性。 可为每次工具调用和 WooCommerce 请求记录 OpenTelemetry 跟踪。
• 经过充分测试。 使用严格的 TypeScript、对每项输入进行 Zod 验证，并针对模拟的 WooCommerce API 进行测试。

快速开始

需要 Node.js 20 或更高版本。

npm install -g @sadrmanesh/woocommerce-mcp

或者运行 GitHub Container Registry 中的 Docker 镜像（支持 linux/amd64 和 linux/arm64，标签为 X.Y.Z、X.Y 和 latest）。Docker Hub 上也提供相同镜像，地址为 Docker Hub，名称为 sadrmanesh/woocommerce-mcp：

docker run --rm -i -e MCP_TRANSPORT=stdio \
  -e WOOCOMMERCE_URL -e WOOCOMMERCE_CONSUMER_KEY -e WOOCOMMERCE_CONSUMER_SECRET \
  ghcr.io/sadrmanesh/woocommerce-mcp:0.6.0

npm 软件包也发布在 GitHub Packages 上；.npmrc 配置请参阅安装选项。npmjs.com 仍是主要注册表。

或者从代码检出目录运行：

git clone https://github.com/sadrmanesh/woocommerce-mcp.git
cd woocommerce-mcp
npm install
npm run build
cp .env.example .env

在 WooCommerce > Settings > Advanced > REST API 下创建 REST API 密钥。店铺为只读时使用 Read 密钥，只有启用写入时才使用 Read/Write 密钥。WordPress 固定链接不能设置为 "Plain"，否则 /wp-json/ 将无法解析。

WOOCOMMERCE_URL=https://store.example.com \
WOOCOMMERCE_CONSUMER_KEY=ck_... \
WOOCOMMERCE_CONSUMER_SECRET=cs_... \
woocommerce-mcp

随后，该进程会通过 stdin 和 stdout 提供 MCP 服务。日志会输出到 stderr。在代码检出目录中运行 npm start 时，会从工作目录加载 .env，且不会覆盖已设置的环境变量。

连接 MCP 客户端

大多数宿主程序都接受如下所示的 mcpServers 映射。密钥应放在 env 中，绝不要放在 args 中。Docker、Smithery 和 MCP Registry 的安装说明见 docs/install.md。

stdio

{
  "mcpServers": {
    "woocommerce": {
      "command": "npx",
      "args": ["-y", "@sadrmanesh/woocommerce-mcp"],
      "env": {
        "WOOCOMMERCE_URL": "https://store.example.com",
        "WOOCOMMERCE_CONSUMER_KEY": "ck_your_consumer_key",
        "WOOCOMMERCE_CONSUMER_SECRET": "cs_your_consumer_secret"
      }
    }
  }
}

从检出目录启动时，使用 "command": "node" 和 "args": ["/absolute/path/to/woocommerce-mcp/dist/index.js"]。

Streamable HTTP

MCP_TRANSPORT=http MCP_HTTP_AUTH_TOKENS="$(openssl rand -base64 32)" woocommerce-mcp

{
  "mcpServers": {
    "woocommerce": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

未进行身份验证时，HTTP 端点仅绑定到环回地址。有关令牌、作用域和 OAuth 内省，请参阅 docs/security.md。

工具、资源和提示词

除 woocommerce_list_stores 外，每个工具都接受可选的 store ID。若未提供，则使用默认商店。

要在浏览器中查看所有工具及其完整输入架构，并构建 tools/call 请求，请打开 Hugging Face 上的工具探索器。

类别	读取工具	写入工具
商店	list_stores
产品	list_products、search_products、get_product	create_product、update_product、bulk_update_products、bulk_adjust_prices
订单	list_orders、get_order、list_order_notes	update_order_status、add_order_note、delete_order_note
履约	get_order_tracking	fulfill_order
退款	list_refunds、get_refund	create_refund
客户	list_customers、get_customer、customer_orders、customer_segments	update_customer
库存	get_stock、low_stock_report	update_stock
优惠券和销售	list_coupons、get_coupon、coupon_performance	create_coupon、update_coupon、delete_coupon、schedule_sale、end_sale
Webhook	list_webhooks、get_webhook、list_webhook_events	create_webhook、update_webhook、delete_webhook
配送和税费	list_shipping_zones、list_shipping_methods、list_tax_rates、list_tax_classes
分析	get_store_summary、sales_analytics

每个名称都以 woocommerce_ 开头，例如 woocommerce_customer_segments。总计 47 个工具：28 个读取工具和 19 个写入工具。

资源

URI	内容
woocommerce://stores	已配置的商店
woocommerce://stores/{store}/products/{id}	一个产品
woocommerce://stores/{store}/orders/{id}	一个订单
woocommerce://stores/{store}/events	最近的 Webhook 投递
woocommerce://stores/{store}/events/{id}	一次包含其负载的 Webhook 投递

提示词： sales_briefing、restock_plan、order_triage 和 price_change_review。

完整的参数和响应详情见 docs/tools.md。

安全写入

1. 只读存储。 只有在 WOOCOMMERCE_READ_ONLY=false（单个存储）或 "readOnly": false（存储列表）时，存储才接受写入。否则，写入工具会在联系存储之前以 read_only 失败。

2. 确认。 当 WOOCOMMERCE_REQUIRE_CONFIRMATION=true（默认值）时，首次调用会返回计划中的请求，且不会进行任何更改：

   {
     "status": "confirmation_required",
     "store": "default",
     "previewId": "pv_4f1c9a2e7b3d0856",
     "message": "The change was NOT applied. ...",
     "request": { "method": "PUT", "path": "orders/1015", "query": {}, "body": { "status": "completed" } }
   }
   

   使用相同参数再次调用该工具并设置 confirm: true，即可应用更改。即使关闭了确认，dryRun: true 也始终只会预览。每次预览都会附带一个 previewId；将其与 confirm: true 一并传回，如果参数自预览后发生了变化，服务会以 preview_mismatch 拒绝调用。

   对于根据存储数据计算写入内容的工具，例如将价格提高 10%，会在预览时解析数据：预览会在 preconditions 下列出读取的每条记录及其当前值（before）和将要写入的绝对值（after），而 previewId 会增加第二部分，用于对这些数据生成指纹。确认时，服务会再次读取相同数据；如果数据发生变化（例如期间价格被编辑），调用会以 stale_preview 拒绝，且不会发送任何内容。关于覆盖范围，请参阅过期预览。

3. 权限范围。 通过经过身份验证的 HTTP 调用时，写入工具还需要 woocommerce:write 权限范围。只读令牌永远无法更改存储。

4. 审计。 将 WOOCOMMERCE_AUDIT_LOG 设置为文件路径或 stderr：

   {"time":"2026-10-30T14:02:11.120Z","tool":"woocommerce_update_order_status","store":"default","outcome":"applied","arguments":{"id":1015,"status":"completed"},"client":"static:3f9a1c2b7d10","previewId":"pv_4f1c9a2e7b3d0856","previewMatch":true}
   

5. 签名审批（可选）。 预览 ID 绑定的是确认的内容，而非确认者的身份：默认情况下，Agent 可以在同一轮中请求预览并确认。设置 WOOCOMMERCE_APPROVAL_SECRET 可要求每次确认都提供 approval 令牌。该令牌是针对确切的 previewId（包括状态部分）、工具、存储和过期时间生成的 HMAC-SHA256 签名，因此不能用于其他参数或已更改的存储。令牌只能使用一次，且默认 10 分钟后过期。人员审核预览后为其签名：

   woocommerce-mcp approve pv_e2a742fe51c807fc_a3510d17b8a51b93 --by "Naser"
   

   该命令会显示审计日志中预览的更改，询问是否确认，并打印令牌，随后 Agent 将令牌作为 approval 与 confirm: true 一并传回。缺少、无效、过期、不匹配或已使用的令牌会分别以 approval_required、approval_invalid、approval_expired、approval_mismatch 和 approval_replayed 拒绝。令牌格式已有文档说明，因此审批页面或 webhook 也可以生成签名。

   请注意：持有密钥的人都可以批准，因此请勿将其放入 MCP 客户端配置、提示词，或任何 Agent 可以使用 shell 的主机中。已使用的令牌按进程存储在内存中。不设置密钥时，行为与 0.5.0 完全相同。请参阅签名审批。

除非通过 apiRefund: true 请求支付网关退还款项，否则 woocommerce_create_refund 创建的退款会记为手动退款。

配置

以下是最常用的设置。所有变量（包括多店铺文件格式）都列在 docs/configuration.md 和 .env.example 中。

变量	默认值	说明
WOOCOMMERCE_URL		店铺源地址，不含 /wp-json
WOOCOMMERCE_CONSUMER_KEY / _SECRET		REST API 凭据
WOOCOMMERCE_READ_ONLY	true	允许对单个店铺执行写入
WOOCOMMERCE_STORES_FILE / WOOCOMMERCE_STORES		多个店铺，使用 JSON 文件或内联 JSON
WOOCOMMERCE_DEFAULT_STORE	第一个店铺	调用未指定 store 时使用的店铺
WOOCOMMERCE_REQUIRE_CONFIRMATION	true	预览写入操作，直到设置 confirm: true
WOOCOMMERCE_AUDIT_LOG	关闭	文件路径或 stderr
WOOCOMMERCE_APPROVAL_SECRET	关闭	每次确认写入时都要求提供签名审批令牌。请勿让 Agent 接触此令牌
WOOCOMMERCE_APPROVAL_TTL_SECONDS	600	服务接受的审批令牌最长有效期
MCP_TRANSPORT	stdio	stdio 或 http
MCP_HTTP_HOST / _PORT / _PATH	127.0.0.1 / 3000 / /mcp	HTTP 监听器
MCP_HTTP_AUTH_TOKENS		完全访问权限的 bearer 令牌
MCP_HTTP_AUTH_READ_TOKENS		只读 bearer 令牌
WOOCOMMERCE_REDACT_PII	false	在结果中屏蔽姓名、电子邮件、电话号码和地址
WOOCOMMERCE_TOOLS_ALLOW / _DENY		要公开或隐藏的工具名称或 * 模式
WOOCOMMERCE_WEBHOOK_SECRET		为店铺启用 webhook 接收器
WOOCOMMERCE_RATE_LIMIT / _BURST	5 / 10	每个店铺每秒请求数及突发请求数
WOOCOMMERCE_CACHE_TTL_MS	0（关闭）	缓存读取响应
WOOCOMMERCE_OTEL_ENABLED	false	导出 OpenTelemetry 跟踪数据

多店铺示例（stores.json）：

{
  "defaultStore": "eu",
  "stores": [
    { "id": "eu", "label": "EU shop", "url": "https://eu.example.com", "consumerKeyEnv": "EU_KEY", "consumerSecretEnv": "EU_SECRET" },
    { "id": "us", "url": "https://us.example.com", "consumerKeyEnv": "US_KEY", "consumerSecretEnv": "US_SECRET", "readOnly": false }
  ]
}

部署

cp .env.example .env    # add store credentials and MCP_HTTP_AUTH_TOKENS
docker compose up -d --build
curl http://127.0.0.1:3000/healthz

该镜像以非 root 用户身份运行，监听 3000 端口，并带有健康检查。远程使用时，请将其置于以 TLS 终止的反向代理后。详见 docs/deployment.md。

开发

npm install
npm run check   # lint, typecheck, tests, build

测试针对模拟的 WooCommerce API 运行，绝不会调用线上店铺。详见 CONTRIBUTING.md。

文档

完整文档站点位于 https://sadrmanesh.github.io/woocommerce-mcp/。本仓库中也包含相同的指南：

• 安装选项
• 配置
• 工具参考
• Webhooks
• 隐私
• 性能
• 安全与身份验证
• 部署
• 可观测性
• 变更日志

技术报告

技术报告：WooCommerce Model Context Protocol Server - A Multi-Store, Previewed Safe-Write Architecture for Autonomous AI Agents in E-Commerce。M. N. Sadrmanesh，Zenodo，2026 年。https://doi.org/10.5281/zenodo.23897615 另见 ResearchGate 和 Academia.edu。

@techreport{sadrmanesh2026woocommercemcp,
  author      = {Sadrmanesh, Mohammad Naser},
  title       = {Technical Report: WooCommerce Model Context Protocol Server - A Multi-Store, Previewed Safe-Write Architecture for Autonomous AI Agents in E-Commerce},
  institution = {Zenodo},
  year        = {2026},
  version     = {1.0},
  doi         = {10.5281/zenodo.23897615},
  url         = {https://doi.org/10.5281/zenodo.23897615}
}

许可证

MIT。版权所有 (c) 2026 Naser Sadrmanesh。详见 LICENSE。

作者

Naser Sadrmanesh：https://github.com/sadrmanesh · https://sadrmanesh.github.io · [email protected]