# WooCommerce MCP Server

An MCP (Model Context Protocol) server that connects LLM agents to a [WooCommerce](https://woocommerce.com/) store via its [REST API](https://developer.woocommerce.com/docs/apis/rest-api/) (`wp-json/wc/v3`). It provides 40 tools covering products, product variations, categories, tags, orders, order notes, refunds, customers, coupons, and sales reports.

## Setup

### 1. Generate WooCommerce API keys

1. In WordPress admin, go to **WooCommerce > Settings > Advanced > REST API**
2. Click **Add key**
3. Give it a description, select a user, and choose **Read/Write** permissions
4. Click **Generate API key** and copy the **Consumer key** and **Consumer secret** immediately (the secret is hidden afterwards)

Your store must use pretty permalinks (Settings > Permalinks) and should be served over HTTPS.

### 2. Install and build

```bash
npm install
npm run build
```

### 3. Configure environment variables

| Variable | Required | Description |
|---|---|---|
| `WOOCOMMERCE_STORE_URL` | Yes | Your store's base URL, e.g. `https://mystore.com` (no trailing slash needed) |
| `WOOCOMMERCE_CONSUMER_KEY` | Yes | Consumer key from step 1 |
| `WOOCOMMERCE_CONSUMER_SECRET` | Yes | Consumer secret from step 1 |
| `WOOCOMMERCE_API_VERSION` | No | Defaults to `wc/v3` |
| `TRANSPORT` | No | `stdio` (default) or `http` |
| `PORT` | No | Port for HTTP transport (default `3000`) |

### 4. Run

**stdio** (for local MCP clients like Claude Desktop):
```bash
WOOCOMMERCE_STORE_URL=https://mystore.com \
WOOCOMMERCE_CONSUMER_KEY=ck_xxx \
WOOCOMMERCE_CONSUMER_SECRET=cs_xxx \
node dist/index.js
```

Example Claude Desktop config entry:
```json
{
  "mcpServers": {
    "woocommerce": {
      "command": "node",
      "args": ["/absolute/path/to/woocommerce-mcp-server/dist/index.js"],
      "env": {
        "WOOCOMMERCE_STORE_URL": "https://mystore.com",
        "WOOCOMMERCE_CONSUMER_KEY": "ck_xxx",
        "WOOCOMMERCE_CONSUMER_SECRET": "cs_xxx"
      }
    }
  }
}
```

**Streamable HTTP** (for remote/multi-client use):
```bash
TRANSPORT=http PORT=3000 \
WOOCOMMERCE_STORE_URL=https://mystore.com \
WOOCOMMERCE_CONSUMER_KEY=ck_xxx \
WOOCOMMERCE_CONSUMER_SECRET=cs_xxx \
node dist/index.js
```
The server listens at `http://localhost:3000/mcp`.

## Tools

All tools are prefixed `woocommerce_` and use snake_case. Every list/get tool accepts a `response_format` parameter (`markdown` default, or `json` for structured data), and list tools support `page`/`per_page` pagination with a consistent envelope (`total`, `count`, `has_more`, `next_page`).

### Products
- `woocommerce_list_products` - search/filter products (status, type, category, tag, stock, price, sale)
- `woocommerce_get_product` - full product detail
- `woocommerce_create_product` / `woocommerce_update_product` / `woocommerce_delete_product`
- `woocommerce_list_product_variations` / `woocommerce_get_product_variation`
- `woocommerce_create_product_variation` / `woocommerce_update_product_variation` / `woocommerce_delete_product_variation`

### Categories & Tags
- `woocommerce_list_product_categories` / `_create_` / `_update_` / `_delete_product_category`
- `woocommerce_list_product_tags` / `_create_` / `_update_` / `_delete_product_tag`

### Orders
- `woocommerce_list_orders` - filter by status, customer, date range, product
- `woocommerce_get_order` - full order detail (line items, addresses, totals)
- `woocommerce_create_order` / `woocommerce_update_order` / `woocommerce_delete_order`
- `woocommerce_list_order_notes` / `woocommerce_create_order_note`
- `woocommerce_list_order_refunds` / `woocommerce_create_order_refund` (destructive financial operation)

### Customers
- `woocommerce_list_customers` / `woocommerce_get_customer`
- `woocommerce_create_customer` / `woocommerce_update_customer` / `woocommerce_delete_customer`

### Coupons
- `woocommerce_list_coupons` / `woocommerce_get_coupon`
- `woocommerce_create_coupon` / `woocommerce_update_coupon` / `woocommerce_delete_coupon`

### Reports
- `woocommerce_get_sales_report` - totals for a period or custom date range
- `woocommerce_get_top_sellers_report` - best-selling products for a period
- `woocommerce_get_report_totals` - status/count breakdown for orders, products, customers, coupons, or reviews

## Design notes

- **Auth**: HTTP Basic Auth with the consumer key/secret, as recommended for HTTPS stores. If your server can't parse Basic Auth headers (rare, usually FastCGI setups), WooCommerce also accepts `consumer_key`/`consumer_secret` as query params - not implemented here since Basic Auth covers the vast majority of installs.
- **Pagination**: mirrors WooCommerce's own `page`/`per_page` model and echoes back `X-WP-Total`/`X-WP-TotalPages` response headers.
- **Response size**: responses are capped at ~25,000 characters; list tools truncate their `items` array with a `truncation_message` telling the agent how to narrow its query instead of silently dropping data.
- **Destructive actions**: `delete_*` and `create_order_refund` tools are annotated `destructiveHint: true`. Deletes default to WooCommerce's trash behavior where supported (`force=false`); refunds are irreversible and the tool description calls this out explicitly.
- **Line-item edits on existing orders** are intentionally out of scope for `woocommerce_update_order` to avoid an agent accidentally corrupting totals/stock counts; use `woocommerce_create_order` for new orders and `woocommerce_create_order_refund` for post-hoc adjustments.

## Development

```bash
npm run dev     # tsx watch mode
npm run build   # compile TypeScript to dist/
npm run clean   # remove dist/
```

Test with the MCP Inspector:
```bash
npx @modelcontextprotocol/inspector node dist/index.js
```