woocommerce-mcp

An MCP server that lets Claude look at a WooCommerce store: orders, products, customers, stock and a sales summary. It talks to the WooCommerce REST API v3 with a normal API key, and it is read-only unless you switch writes on.

Works with Claude Desktop, Claude Code and any other MCP client that can start a stdio server.

What it looks like in use

Once the server is connected you can ask things like:

• "What sold best in the last 30 days?"

• "Which products are below 5 in stock?"

• "What do I need to reorder first?"

• "Show me the open orders from ann@example.com"

• "Set the stock of SKU MUG-1 to 40" (only with writes enabled)

Claude picks the tool, the server answers with trimmed JSON, Claude explains it.

Related MCP server: mcp-woocommerce

Install

Python 3.10 or newer.

pipx install git+https://github.com/inmanjeffrey89-cell/woocommerce-mcp

or

pip install git+https://github.com/inmanjeffrey89-cell/woocommerce-mcp

Either one puts a woocommerce-mcp command on your PATH. python -m woocommerce_mcp does the same thing.

Get API keys from WooCommerce

In the WordPress admin go to WooCommerce > Settings > Advanced > REST API and click "Add key". Pick a user who can manage the store, set permissions to Read, and generate. Copy the consumer key and consumer secret right away; WooCommerce shows the secret once.

Read is enough for everything except update_stock and update_order_status. If you want those, create the key with Read/Write and set WC_ALLOW_WRITES=true (see below).

The store needs to be on HTTPS. WooCommerce only accepts key and secret authentication over HTTPS.

Configure

The server reads four environment variables:

If one of the required variables is missing the server prints which one and exits instead of starting.

Claude Desktop

Add this to claude_desktop_config.json (Settings > Developer > Edit Config):

{
  "mcpServers": {
    "woocommerce": {
      "command": "woocommerce-mcp",
      "env": {
        "WC_URL": "https://shop.example",
        "WC_CONSUMER_KEY": "ck_xxx",
        "WC_CONSUMER_SECRET": "cs_xxx"
      }
    }
  }
}

Claude Desktop does not read your shell PATH. If it reports that the server failed to start, replace "woocommerce-mcp" with the full path that which woocommerce-mcp prints.

Claude Code

claude mcp add woocommerce \
  -e WC_URL=https://shop.example \
  -e WC_CONSUMER_KEY=ck_xxx \
  -e WC_CONSUMER_SECRET=cs_xxx \
  -- woocommerce-mcp

Add -e WC_ALLOW_WRITES=true to enable writes. Check with claude mcp list.

Tools

Read tools (always on):

Write tools (need WC_ALLOW_WRITES=true):

With writes off, both tools answer with a short message saying writes are disabled and do nothing else.

Every tool declares all four MCP tool hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), so a client that checks them can tell the eight read tools from the two that change the store. update_order_status is marked open-world because a status change can make WooCommerce email the customer.

There is also one resource, woocommerce://store, with the store URL, WooCommerce and WordPress versions, currency, timezone and whether writes are enabled.

Money values are passed through as strings exactly as WooCommerce reports them, with the currency code alongside. Dates go in and come out in the store's timezone.

About WC_ALLOW_WRITES

update_order_status triggers the same side effects as changing the status in the admin: customer emails go out, stock can be released or restocked, and payment gateways may react. Setting an order to refunded only changes the label; no money moves. update_stock overwrites the quantity and turns on stock management for that product.

Leave writes off unless you need them, and when you turn them on, read what Claude proposes before you approve the tool call.

Errors

Bad keys, missing orders, a store that is not reachable, rate limits and non-JSON responses all come back as a plain sentence that says what went wrong and, where it helps, what to check. Claude sees the sentence, not a stack trace.

Limits worth knowing

• sales_summary, low_stock_report and restock_priority walk the whole result set 100 items at a time. They stop at 5,000 items and set truncated: true in the result when that happens.

• low_stock_report checks published products. Pass include_variations: true to also check each variable product's variations; that costs one request per variable product. With it off, variable_products_unchecked says how many variable products were skipped.

• Products and variations with stock management off have no quantity to compare, so they never count as low. They show up in untracked_count, with up to 10 of them in untracked_examples, so a "nothing is low" answer can say what it couldn't check.

• restock_priority counts completed and processing orders from the last 30 days by default (days, status) and lists items with under 14 days of stock left (cover_days). An item that sold nothing in the window is left out, even if it was out of stock the whole time, so run low_stock_report too. Variable products work as in low_stock_report; when stock is kept on the parent, every variation's sales count against it.

• The woocommerce://store resource reads system_status, which WooCommerce only shows to users who can manage the store. With a more limited key you still get the URL and the writes flag.

Development

git clone https://github.com/inmanjeffrey89-cell/woocommerce-mcp
cd woocommerce-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
ruff check .

The tests mock every HTTP call, so they run without a store. To try the read tools against a real store, export the three variables and run:

python scripts/smoke_live.py

It prints what each read tool returns and never writes anything.

License

MIT. See LICENSE.