mcp-server-woocommerce

MCP server for managing WooCommerce stores through AI assistants like Claude. Provides 101 tools covering products, orders, customers, coupons, shipping, taxes, webhooks, settings, reports, and more.

Quick Start

1. Get WooCommerce API keys

In your WordPress admin: WooCommerce > Settings > Advanced > REST API > Add key with Read/Write permissions.

2. Add to your AI tool

No install needed — runs directly via npx:

Claude Code

Add to your project's .mcp.json:

config.json

{
  "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"
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

config.json

{
  "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"
      }
    }
  }
}

Cursor

Install in Cursor (one-click) or add to .cursor/mcp.json in your project root:

config.json

{
  "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. Start using it — ask your AI assistant things like:

"List all products that are out of stock" "Create a 10% off coupon for orders over $50" "Show me this week's sales report"

Features

Full store management — CRUD operations for products, categories, tags, brands, orders, customers, and coupons
Product taxonomy — attributes, attribute terms, and variations with batch support
Shipping — zones, zone methods, and shipping classes
Taxes — tax rates and tax classes
Webhooks — create, manage, and monitor webhook subscriptions
Settings — read and update store configuration
Reports — sales reports, top sellers, order/product/customer totals
Media management — list, delete, and cleanup orphaned media via WordPress REST API
Token optimization — all tools support a fields param to return only specific fields, reducing response size by 60-97%
MCP resources — schema references for products, orders, coupons, refunds, and payment gateways that agents can read for context
Guided prompts — multi-step workflows for variable product setup, order processing, and catalog overview
Tool annotations — readOnlyHint, destructiveHint, and idempotentHint on all 101 tools for safe agent behavior
Actionable errors — error responses include guidance on how to fix common issues

Safety

This server connects to a LIVE WooCommerce store. Every create, update, and delete operation affects real data. Use caution, especially on production stores.

Before You Start

Back up your store before using destructive tools. Use a WordPress backup plugin or your host's backup feature.
Test on staging first. Clone your production store to a staging environment and point this server at the staging URL.
Use read-only mode when exploring. Set WOOCOMMERCE_MCP_READ_ONLY=true to block all write operations — only list, get, and report tools will work.

Irreversible Operations

Most delete operations move items to trash (recoverable). However, these are permanent and cannot be undone:

Tool	Why it's irreversible
`delete_media`	WordPress media deletions bypass trash entirely
`delete_tax_rate`	Tax rates have no trash — deleted immediately
`delete_tax_class`	Tax classes have no trash — rates become orphaned
`delete_attribute`	Removes the attribute AND all its terms from every product
`delete_refund`	Removes refund record (does not reverse payment)
`cleanup_orphaned_media`	Permanently deletes all unattached media when `delete=true`
`run_system_tool`	System maintenance actions (cache clears, DB updates) cannot be undone

Cascading Effects

Some operations affect more than the single item being changed:

Deleting an attribute removes it from all products — variable products may break
Deleting an attribute term removes that option from all products and variations
Deleting a shipping zone removes all methods and locations in that zone
Batch operations (batch_update_attribute_terms, batch_update_variations) can create, update, AND delete in a single call

API Key Permissions

For maximum safety, create WooCommerce API keys with only the permissions you need:

Read-only exploration: Create a key with Read permissions only
Full management: Use Read/Write permissions

Available Tools (101)

Domain	Tools
Products	list, get, create, update, delete
Categories	list, get, create, update, delete
Tags	list, get, create, update, delete
Brands	list, get, create, update, delete
Attributes	list, get, create, delete
Attribute Terms	list, create, delete, batch update
Variations	list, get, create, update, batch update
Orders	list, get, create, update, delete
Order Refunds	list, create, delete
Order Notes	list, create, delete
Customers	list, get, create, update
Coupons	list, get, create, update, delete
Product Reviews	list, get, update, delete
Shipping Zones	list, get, create, update, delete
Shipping Zone Methods	list, get, create, update, delete
Shipping Classes	list, create
Tax Rates	list, get, create, update, delete
Tax Classes	list, create, delete
Webhooks	list, get, create, update, delete
Payment Gateways	list, get, update
Settings	list groups, get, update
System Status	get status, list tools, run tool
Data	list countries, list currencies
Reports	sales, top sellers, order/product/customer totals
Media	list, delete, cleanup orphaned

Resources

The server exposes 7 MCP resources that provide schema references and guides for AI agents:

URI	Description
`woo://schema/product`	Product fields, types, statuses, and key rules
`woo://schema/order`	Order fields, status lifecycle, and payment info
`woo://schema/coupon`	Coupon types, limits, restrictions, and rules
`woo://schema/refund`	Refund fields, reasons, line items, and processing rules
`woo://reference/product-types`	When to use simple, variable, grouped, or external products
`woo://reference/order-statuses`	Order status transitions and lifecycle diagram
`woo://reference/payment-gateways`	Available payment gateways and their configuration options

Resources are read-only context that agents can fetch to understand WooCommerce data structures before making API calls.

Prompts

5 guided workflow prompts that orchestrate multi-step operations:

Prompt	Args	What it does
`setup_variable_product`	`product_name`, `attribute_name`, `variations`	Creates a variable product end-to-end: attribute → terms → product → variations → publish
`process_order`	`order_id`	Reviews an order's details and recommends the appropriate status transition
`catalog_overview`	(none)	Runs 5 tools in parallel to produce a store dashboard (products, orders, customers, categories, top sellers)
`handle_refund`	`order_id`	Guides through refund processing: review order, select items, create refund, verify
`moderate_reviews`	(none)	Reviews pending product reviews and recommends approve/update/delete actions

Tool Annotations

Every tool is annotated with behavior hints so AI agents can make safe decisions:

Annotation	Meaning	Applied to
`readOnlyHint`	No side effects, safe to call anytime	All `list_`, `get_`, and report tools (46)
`destructiveHint`	Deletes or removes data	All `delete_` tools + `cleanup_orphaned_media` + `run_system_tool` + `batch_update_` (22)
`idempotentHint`	Safe to retry, same result each time	All `update_*` tools (15)

All tools also set openWorldHint: false — they only interact with WooCommerce, no external side effects.

Configuration

Environment Variables

Variable	Required	Description
`WORDPRESS_SITE_URL`	Yes	WordPress store URL (e.g. `https://store.example.com`)
`WOOCOMMERCE_CONSUMER_KEY`	Yes	WooCommerce REST API consumer key (`ck_...`)
`WOOCOMMERCE_CONSUMER_SECRET`	Yes	WooCommerce REST API consumer secret (`cs_...`)
`WORDPRESS_USERNAME`	No	WordPress admin username (for media tools)
`WORDPRESS_APP_PASSWORD`	No	WordPress Application Password (for media tools)
`MCP_TRANSPORT`	No	Set to `http` for remote HTTP access (default: `stdio`)
`PORT`	No	Platform-provided port (Hostinger, Railway); overrides `MCP_PORT`
`MCP_PORT`	No	HTTP server port (default: `3000`)
`MCP_AUTH_TOKEN`	No*	Bearer token for HTTP auth (*required when `MCP_TRANSPORT=http`)
`WOOCOMMERCE_MCP_READ_ONLY`	No	Set to `true` to block all write/delete operations (safe exploration mode)

Using a `.env` file

Instead of inlining credentials, point to a directory with a .env file:

config.json

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

Multiple Stores

Use different server names to manage multiple stores from one project:

config.json

{
  "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", "..." }
    }
  }
}

Token Optimization

All tools support an optional fields param (comma-separated) to return only specific fields:

text

# 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"

This reduces response size by 60-97%, keeping AI context windows focused and costs low.

Development

bash

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

bash

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

Integration tests run against a real WordPress 6.9.4 + WooCommerce 10.5.3 instance via @wordpress/env. Prerequisite: Docker. The test environment starts automatically when you run pnpm test:integration.

Docker

Terminal

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

Remote / Mobile Access (HTTP Transport)

For accessing your WooCommerce tools from Claude mobile, ChatGPT, or other remote clients, run the server in HTTP mode:

bash

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

Or with Docker:

Terminal

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

Variable	Default	Description
`MCP_TRANSPORT`	`stdio`	Set to `http` for remote access
`PORT`	—	Platform-provided port (overrides `MCP_PORT`)
`MCP_PORT`	`3000`	HTTP server port
`MCP_AUTH_TOKEN`	—	Bearer token for authentication (Claude Desktop/Code)
`AUTH0_DOMAIN`	—	Auth0 tenant URL for OAuth 2.1 (Claude.ai Connectors)
`AUTH0_AUDIENCE`	—	Auth0 API identifier for OAuth 2.1
`MCP_SERVER_URL`	—	Public server URL for OAuth 2.1 discovery

Either MCP_AUTH_TOKEN or AUTH0_DOMAIN + AUTH0_AUDIENCE + MCP_SERVER_URL is required.

Deployment guide: See docs/DEPLOYMENT.md for step-by-step instructions for Railway (~~$0/mo), Fly.io (~~$0/mo with scale-to-zero), and Docker deployments.

Claude Desktop / Code: Use bearer token auth — add the server URL and Authorization: Bearer <token> header to your config.

Claude.ai web / mobile: Requires OAuth 2.1 via Auth0 (free tier). See the deployment guide for setup instructions.

Default mode remains stdio — existing npx users are unaffected.

License

MIT

WooCommerce is a registered trademark of Automattic Inc. This project is not affiliated with, endorsed by, or sponsored by Automattic Inc.

mcp-server-woocommerce

Quick Start

Features

Safety

Before You Start

Irreversible Operations

Cascading Effects

API Key Permissions

Available Tools (101)

Resources

Prompts

Tool Annotations

Configuration

Environment Variables

Using a .env file

Multiple Stores

Token Optimization

Development

Docker

Remote / Mobile Access (HTTP Transport)

License

Using a `.env` file