WooCommerce MCP Server (woocommerce-mcp-server)

MCP server for WooCommerce: 8 read tools (orders, products, low stock, sales summary, customers) and 6 write proposals that require human approval before being applied. Read-only by default, PII redacted before it reaches the model, separate approver token, stdio and Streamable HTTP, Docker image, tested against a fake WooCommerce REST API in CI. MIT.

GitHub

Documentation

woocommerce-mcp-server

An MCP server that lets an AI agent work with a WooCommerce store — read everything it needs, and change nothing without a human saying yes.

Version française plus bas

Connect Claude Desktop, Cursor, or your own agent to a store and ask: "Which products are about to run out?", "Where is order 500?", "How did we do this month vs last month?". When the agent wants to change something — set an order to completed, refund 19 €, drop a price — it files a proposal with a reason. You approve it from the CLI or an admin endpoint the agent has no token for. Only then can it be applied.

agent  → propose_refund(order 500, 19.00, "Cap arrived damaged")       status: pending
human  → woocommerce-mcp-server approve 3f9c                         status: approved
agent  → apply_proposal(3f9c)                                         POST /orders/500/refunds  ✓

Built after wiring agents into client stores: the useful part was never "can the model call the API", it was what the model is allowed to see and do, and who signs off.

Tools

Read (always on)	Write (proposal → human approval → apply)
`store_info` versions, currency, enabled gateways	`propose_order_note` private or customer-visible
`list_products` search / sku / status / stock / category	`propose_order_status`
`get_product` by id or SKU, with variations	`propose_stock_update` product or variation
`low_stock_products` honours each product's own threshold	`propose_price_update` regular / sale
`list_orders` status, dates, customer, search	`propose_refund` manual or via gateway
`get_order` with notes	`list_proposals`
`search_customers`	`apply_proposal` — refused unless approved and `WOO_ALLOW_WRITES=true`
`sales_summary` week / month / last_month / year / range
`list_coupons` validity, usage, expiry flags

Every tool carries MCP annotations (readOnlyHint, destructiveHint) so clients can show the right confirmation UI.

Safety defaults

Read-only unless WOO_ALLOW_WRITES=true. Proposals are still recorded, so you can run it read-only and review what the agent would have done.
PII masked: emails → m***@example.com, phones → ***78, names → initials, street lines and IPs dropped. City, postcode and country stay for shipping questions. WOO_REDACT_PII=false to disable.
Separate approver identity: in HTTP mode the agent uses MCP_HTTP_TOKEN, approvals need MCP_ADMIN_TOKEN, and the server refuses to start if they're equal.
Idempotent gate: a proposal is applied at most once; its result or error is stored with it.
Input is validated with zod before any request reaches the store.

Install

npm i -g woocommerce-mcp-server          # or: npx woocommerce-mcp-server

Create a REST API key in WooCommerce → Settings → Advanced → REST API (Read permission is enough for read-only use).

Claude Desktop / Cursor (stdio)

{
  "mcpServers": {
    "woocommerce": {
      "command": "npx",
      "args": ["-y", "woocommerce-mcp-server"],
      "env": {
        "WOO_URL": "https://shop.example.com",
        "WOO_CONSUMER_KEY": "ck_…",
        "WOO_CONSUMER_SECRET": "cs_…"
      }
    }
  }
}

Server mode (Streamable HTTP)

cp .env.example .env   # fill it in, with two different tokens
woocommerce-mcp-server http --port 3333
# agent:  POST http://host:3333/mcp          Authorization: Bearer $MCP_HTTP_TOKEN
# human:  GET  http://host:3333/proposals    Authorization: Bearer $MCP_ADMIN_TOKEN
#         POST http://host:3333/proposals/<id>/approve   (or /reject)

Docker:

docker run -d --env-file .env -v woo-proposals:/data -p 3333:3333 ghcr.io/walidsadfi-evolurise/woocommerce-mcp-server

Reviewing proposals from the terminal

$ woocommerce-mcp-server proposals
3f9c1a2e  pending   refund         Refund 19.00 on order #500 (manual): Cap arrived damaged
          reason: Photo received from customer, cap crushed in transit
$ woocommerce-mcp-server approve 3f9c
approved: Refund 19.00 on order #500 (manual): Cap arrived damaged

The proposals file (WOO_PROPOSALS_FILE) is plain JSON, so the approver can be a different process, a cron that posts to Slack, or a tiny back-office page.

Compared with the official WooCommerce MCP (developer preview)

WooCommerce now exposes its own MCP surface through the WordPress Abilities API plus the separate MCP Adapter plugin. Both are legitimate; they solve different problems.

	Official WooCommerce MCP (preview)	woocommerce-mcp-server
Runs	Inside WordPress (plugin + WP-CLI for stdio, HTTP via a Node proxy)	Outside the site, against the REST API — nothing to install on the store
Auth	WordPress user + Application Password (HTTP), `--user` with WP-CLI (stdio)	WooCommerce REST API key, Read permission is enough for read-only use
Tools	3 generic tools (`discover`, `get-info`, `execute` ability) over product/order abilities	8 read tools shaped for store questions (`low_stock_products`, `sales_summary`…) + 6 write proposals
Writes	Direct: create/update/delete products, update order status, add notes	Proposal → human approval → apply, disabled unless `WOO_ALLOW_WRITES=true`
Personal data	Returned as-is; the docs advise a dedicated user because order and customer operations can expose personal data	Redacted by default before it reaches the model (emails, phones, names, street lines, IPs)
Approver identity	Same credentials as the agent	Separate admin token; the server refuses to start if both tokens are equal
Status	Developer preview — breaking changes expected, old `/wp-json/woocommerce/mcp` endpoint removed in 11.3	Stable API, tested against a fake WooCommerce REST API in CI

Use the official one when you want the Abilities ecosystem and are fine giving the agent a WordPress login. Use this one when the agent must not hold admin rights, someone has to sign off on every change, and customer data should stay out of the context window. They can run side by side.

Development

npm ci
npm test            # vitest against an in-process fake WooCommerce API
npm run lint && npm run typecheck && npm run build

Tests spin up a fake WooCommerce REST API (test/mock-woo.ts) and talk to the server through the real MCP client over in-memory and HTTP transports, so the suite covers transport, validation, redaction and the whole proposal lifecycle without touching a store.

Roadmap

Resources: woo://orders/{id} for clients that prefer resources over tools
Prompts: daily store briefing, "handle this support ticket"
Shipping zones (read)
Webhook listener → MCP notifications on new orders

License

MIT — see LICENSE. Built by Walid Sadfi, Forward Deployed Engineer · agents IA & WooCommerce. See also woocommerce-agent-ready, which audits a store for the agentic-commerce protocols (Store API, MCP, structured data).

Version française

Un serveur MCP qui permet à un agent IA de travailler avec une boutique WooCommerce : lire tout ce dont il a besoin, et ne rien modifier sans qu'un humain dise oui.

Branchez Claude Desktop, Cursor ou votre propre agent sur une boutique et demandez : « Quels produits vont être en rupture ? », « Où en est la commande 500 ? », « Comment s'est passé le mois par rapport au précédent ? ». Quand l'agent veut modifier quelque chose (passer une commande en terminée, rembourser 19 €, baisser un prix), il dépose une proposition motivée. Vous l'approuvez depuis le terminal ou un endpoint admin dont l'agent n'a pas le token. Seulement ensuite, elle peut être appliquée.

Lecture seule par défaut (WOO_ALLOW_WRITES=false) : les propositions sont tout de même enregistrées, idéal pour observer ce que l'agent aurait fait.
Données personnelles masquées par défaut : emails, téléphones, noms et adresses postales ; la ville et le pays restent pour les questions de livraison.
Deux identités en mode HTTP : token agent et token approbateur, obligatoirement différents.
Une proposition s'applique au plus une fois, avec son résultat ou son erreur archivé.
Transports stdio et HTTP, image Docker, 27 tests contre une fausse API WooCommerce.

npx woocommerce-mcp-server            # stdio, pour Claude Desktop / Cursor
woocommerce-mcp-server http           # mode serveur
woocommerce-mcp-server proposals      # relire ce que l'agent propose
woocommerce-mcp-server approve <id>

Vous voulez ça branché sur votre boutique, avec un process de validation qui colle à votre équipe et un point de mesure ? Parlons-en sur Malt.