WooCommerce MCP setup
With the WooCommerce add-on you ask Claude about orders, products and customers in your store. You need two things from your store: its address and an API key. This page shows where to find them.
What you need
- Admin access to your WooCommerce store.
- A store that opens with https://.
- About five minutes.
- A seat on MCP Hosted, or MCP Self-hosted, with the WooCommerce add-on.
Where to find it
Your store address
This is the address your customers use, for example https://www.example.com. If your shop lives in a subfolder, add that too, for example https://www.example.com/shop.
Your API key
The API key is a pair: a consumer key that starts with ck_ and a consumer secret that starts with cs_.
- Log in to your WordPress admin and go to WooCommerce, Settings, Advanced, REST API.
- Choose Add key. Use AddoCore as the description and pick an admin user.
- Set Permissions to Read. Choose Read/Write only if a seat may make changes.
- Choose Generate API key.
- Copy the consumer key and the consumer secret. WooCommerce shows the secret only once.
Lost the secret? Revoke the key and make a new one.
Paste it in AddoCore
- In My Account, open MCP Hosted and pick your seat. On MCP Self-hosted, open your license.
- Go to Tools and choose Set up on the WooCommerce card.
- Choose Save login details, then Test connection. A green result means it works.
One seat can use several stores. Add each store with its own API key. We store your login details encrypted.
About the WooCommerce add-on · Connect Claude to WooCommerce: how it works · All setup guides
Running it yourself
Only for MCP Self-hosted when you set things in the .env file instead of in My Account. With the steps above you do not need this.
Show the technical setup
A WooCommerce MCP setup takes three things: the WooCommerce entitlement on your mcp-core license, a REST API key pair from your store, and four lines in .env. After a restart, Claude can list and read orders, products and customers. Write tools stay hidden until a seat is set to read-write.
What do you need before the WooCommerce MCP setup?
You need a running mcp-core installation and the WooCommerce add-on on the same license. If mcp-core is not installed yet, follow the mcp-core install guide first and come back to the WooCommerce MCP setup.
- An active mcp-core license with the
tool:woocommerceentitlement. Buy the WooCommerce MCP server add-on if you don’t have it. - A WooCommerce store reachable over HTTPS. The tool authenticates with HTTP Basic, which is only safe over HTTPS.
- Admin access to that store, to create the REST API keys.
- At least one seat in My Account → MCP Self-hosted with the WooCommerce tool ticked.
Bought the add-on after your first install? No new download is needed. The add-on is added to your existing license, and you receive an email listing the env vars the tool needs.
Where do you get the WooCommerce REST API keys?
You create the keys in the store itself, under WooCommerce → Settings → Advanced → REST API. Click “Add key”, give it a description such as “mcp-core”, pick the user the key acts as, and choose the permissions. This is the only part of the WooCommerce MCP setup that happens in the store itself.
- Read is enough when Claude only needs to look things up.
- Read/Write is needed for the write tools: order status, order notes and stock.
WooCommerce shows the consumer key (starts with ck_) and the consumer secret (starts with cs_) once. Copy both straight into your .env. If you lose the secret, revoke the key and create a new one.
Which env vars does the WooCommerce MCP setup use?
The tool reads four variables for a single store, plus one for multiple stores. The .env in your download already contains the required lines, empty, and the optional ones commented out.
| Variable | Required | Default | Purpose |
|---|---|---|---|
WOOCOMMERCE_STORE_URL | Yes (single store) | none | Store base URL, e.g. https://shop.example.com, no trailing path |
WOOCOMMERCE_CONSUMER_KEY | Yes (single store) | none | The ck_ key |
WOOCOMMERCE_CONSUMER_SECRET | Yes (single store) | none | The cs_ secret |
WOOCOMMERCE_MODE | No | read-only | Fallback mode; the mode set on the seat takes precedence |
WOOCOMMERCE_CONNECTIONS | No | none | JSON array for several stores; replaces the three scalar vars |
A minimal single-store .env block:
WOOCOMMERCE_STORE_URL=https://shop.example.com
WOOCOMMERCE_CONSUMER_KEY=ck_xxxxxxxxxxxxxxxx
WOOCOMMERCE_CONSUMER_SECRET=cs_xxxxxxxxxxxxxxxxThe tool calls /wp-json/wc/v3 on that URL. You can also store these values in My Account → MCP Self-hosted → Tools. They are kept encrypted there, a running mcp-core picks them up without a new download, and they override the same keys in .env.
How do you connect several stores in one WooCommerce MCP setup?
Set WOOCOMMERCE_CONNECTIONS to a JSON array with one object per store. Once it is set, the three scalar variables are ignored, not merged.
WOOCOMMERCE_CONNECTIONS=[{"id":"shop-a","label":"Main store","url":"https://shop-a.example.com","consumerKey":"ck_...","consumerSecret":"cs_..."},{"id":"shop-b","label":"Outlet","url":"https://shop-b.example.com","consumerKey":"ck_...","consumerSecret":"cs_..."}]Every entry needs id, url, consumerKey and consumerSecret; label is optional. With two or more stores, every WooCommerce tool gets a required store parameter, and Claude picks the store by its id. Keep the ids short and stable. With one store, that parameter does not exist.
Read-only or read-write: what changes in the WooCommerce MCP setup?
In read-only mode the write tools are not registered at all, so Claude never sees them. The mode is set per seat: when you add a seat in My Account → MCP Self-hosted → Seats, you pick read-only or read-write for each tool. WOOCOMMERCE_MODE is only the fallback. The difference between buying a tool and its mode is explained in entitlements vs. tool modes.
| Mode | Tools Claude sees |
|---|---|
| read-only | woocommerce_list_orders, woocommerce_get_order, woocommerce_list_products, woocommerce_get_product, woocommerce_list_customers |
| read-write | All of the above, plus woocommerce_update_order_status, woocommerce_add_order_note, woocommerce_update_stock |
List tools return 10 results by default and up to 100 per page. woocommerce_update_stock only works on products with “Manage stock” enabled; the tool does not switch that setting on for you. Order notes are internal unless Claude marks them as a customer note.
How do you start the tool and test the WooCommerce MCP setup?
Run the update script from the folder you unzipped. It pulls the image and restarts mcp-core with your new .env.
./mcp-update.shJust bought the add-on and the tool doesn’t show? Force a license check instead of waiting for the next one:
docker exec mcp-core npm run refresh-licenseThen open Claude and ask it to call mcp_status. That built-in tool lists the license state, your seat and its tools with their modes. Ask for “the last five orders” as a first real test. To tie a client to the right seat, see MCP seats.
Which errors do you see during a WooCommerce MCP setup?
Most problems come from missing values, bad JSON or key permissions. The messages below come straight from the tool.
- No WooCommerce tools at all: the container log says “No WooCommerce store is configured”. Fill in the three scalar vars or
WOOCOMMERCE_CONNECTIONSand run./mcp-update.sh. Also check the entitlement and that the seat has WooCommerce ticked. - “WOOCOMMERCE_CONNECTIONS is not valid JSON” or “is missing url/consumerKey/consumerSecret”: fix the array. Put it on one line, use double quotes, no trailing commas.
- “Multiple WooCommerce stores are configured — pass the store parameter” or “Unknown WooCommerce store”: Claude used a wrong or missing id. The message lists the configured ids.
- “WooCommerce [id] API error 401”: wrong key or secret, or the key was revoked. Create a new key pair and check that the URL uses HTTPS.
- A write tool fails while reads work: the key has Read permission only. Create a Read/Write key and replace both values.
Your WooCommerce MCP setup is done when mcp_status shows the tool and a test query returns orders. For the other add-ons, go back to the MCP setup guides.
Ready to try it?