# woo-mcp

A read-only [MCP](https://modelcontextprotocol.io) server that lets Claude answer questions about a WooCommerce store: orders, customers, sales, stock. It only sends `GET` requests and never changes anything in the store.

## Tools

| Tool | Answers |
|---|---|
| `list_customers`, `get_customer` | Who are my customers? Details by ID, email or name |
| `get_order`, `list_orders` | One order, a customer's orders (including guest checkouts), orders by date |
| `get_order_count` | How many orders, optionally per day / month / year |
| `get_product_sales` | How many times was product X bought (by ID, SKU or name) |
| `get_stuck_orders` | Which orders are stuck in processing / on-hold |
| `get_failed_payments` | Failed and pending payments, with contact details and the amount at stake |
| `get_top_products`, `get_top_categories`, `get_top_customers` ¹ | Best sellers and best customers |
| `get_new_vs_returning` ¹ | New vs returning customers, by orders and revenue |
| `get_low_stock_products`, `get_dead_stock` ¹ | What's running out, and what isn't selling |

¹ Uses WooCommerce Analytics. Enable it and run **WooCommerce → Analytics → Settings → Import historical data** once. The stock tools only see products with stock management turned on.

## Setup

Requires Node.js 20.12+.

```bash
npm install
npm run build
cp .env.example .env   # then fill it in
```

Create the API key in **WooCommerce → Settings → Advanced → REST API** with **Read** permission. The store must use https.

| Variable | Default | |
|---|---|---|
| `WOO_URL` | | `https://your-store.com` |
| `WOO_CONSUMER_KEY` / `WOO_CONSUMER_SECRET` | | `ck_...` / `cs_...` |
| `WOO_QUERY_STRING_AUTH` | `false` | Set `true` if you get 401 with correct keys |
| `WOO_CONCURRENCY` | `5` | Max parallel requests to the store (1–20) |
| `WOO_TIMEOUT_MS` | `30000` | Per-request timeout |

## Connect

**Claude Code:**

```bash
claude mcp add woo --scope user -- node /path/to/woo-mcp/dist/index.js
```

**Claude Desktop** (Settings → Developer → Edit Config):

```json
{ "mcpServers": { "woo": { "command": "node", "args": ["/path/to/woo-mcp/dist/index.js"] } } }
```

Then just ask: "What's the latest order?", "What sold best this month?", "Which orders are stuck?"

## Development

```bash
npm test          # build + end-to-end tests against a fake store
npm run inspect   # MCP Inspector in the browser
```

Architecture, request costs and security details: [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).

## License

[Apache 2.0](LICENSE). You're free to use, modify and distribute this code, including commercially, as long as you credit the author: keep the [NOTICE](NOTICE) file and the copyright notice with any copy or derivative work.