# mcp-server-woocommerce

[![CI](https://github.com/AmitGurbani/mcp-server-woocommerce/actions/workflows/ci.yml/badge.svg)](https://github.com/AmitGurbani/mcp-server-woocommerce/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/@amitgurbani/mcp-server-woocommerce)](https://www.npmjs.com/package/@amitgurbani/mcp-server-woocommerce)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)

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`:

<details open>
<summary><strong>Claude Code</strong></summary>

Add to your project's `.mcp.json`:

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

</details>

<details>
<summary><strong>Claude Desktop</strong></summary>

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

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

</details>

<details>
<summary><strong>Cursor</strong></summary>

[Install in Cursor](cursor://settings/mcp/add?name=woocommerce&type=stdio&command=npx&args=-y,@amitgurbani/mcp-server-woocommerce) (one-click) or add to `.cursor/mcp.json` in your project root:

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

</details>

**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:

```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:

```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`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/). Prerequisite: Docker. The test environment starts automatically when you run `pnpm test:integration`.

### Docker

```bash
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:

```bash
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](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](docs/DEPLOYMENT.md#auth0-setup-for-claude-connectors) 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.