# mcp-woocommerce

Production-grade MCP server for the **WooCommerce REST API** -- 73 tools for products, variations, attributes, orders, customers, coupons, reviews, reports, shipping, payments, webhooks, batch operations, inventory, and system management.

## Why This Exists

WooCommerce powers **36% of all e-commerce** (5M+ active stores) but has zero comprehensive MCP servers. This fills that gap with 73 production-ready tools covering the entire WooCommerce REST API v3 with full CRUD on every core resource.

## Features

- **73 tools** across 18 categories -- the most comprehensive WooCommerce MCP server available
- **Full CRUD** for products, variations, attributes, attribute terms, categories, tags, reviews, orders, customers, coupons, and webhooks
- **Inventory management** -- list out-of-stock and low-stock products
- **Batch operations** -- bulk update products and orders in a single call
- **Reports & analytics** -- sales reports, top sellers, order/product totals
- **Store configuration** -- settings, tax classes, shipping classes, currencies, countries
- **Webhook management** -- create, update, list, delete webhooks for real-time events
- **System diagnostics** -- WooCommerce/WordPress versions, plugins, server environment
- **Error-safe** -- every tool wrapped with error handling, never crashes on API failures
- **Simple auth** -- consumer key + secret via environment variables

## Quick Start

### Install

```bash
pip install mcp-woocommerce
```

### Configure

Set your WooCommerce REST API credentials as environment variables:

```bash
export WOOCOMMERCE_URL="https://yourstore.com"
export WOOCOMMERCE_KEY="ck_your_consumer_key"
export WOOCOMMERCE_SECRET="cs_your_consumer_secret"
```

Generate API keys at: **WordPress Admin > WooCommerce > Settings > Advanced > REST API**

### Run

```bash
mcp-woocommerce
```

Or run as a module:

```bash
python -m mcp_woocommerce
```

### Use with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "woocommerce": {
      "command": "mcp-woocommerce",
      "env": {
        "WOOCOMMERCE_URL": "https://yourstore.com",
        "WOOCOMMERCE_KEY": "ck_your_consumer_key",
        "WOOCOMMERCE_SECRET": "cs_your_consumer_secret"
      }
    }
  }
}
```

### Use with Claude Code

```bash
claude mcp add woocommerce -- mcp-woocommerce
```

Then set environment variables in your shell before running Claude Code.

## Tools (73)

### Store (1)
| Tool | Description |
|------|-------------|
| `ping` | Validate connection and get store info |

### Products (8)
| Tool | Description |
|------|-------------|
| `list_products` | List products with filters (status, category, search, on_sale) |
| `get_product` | Full product details (pricing, inventory, images, attributes) |
| `create_product` | Create a product (simple, variable, grouped, external) |
| `update_product` | Update product fields (price, stock, status, etc.) |
| `delete_product` | Delete or trash a product |
| `search_products` | Search by name or SKU |
| `list_low_stock_products` | List products by stock status (out-of-stock, on-backorder) |

### Product Categories (4)
| Tool | Description |
|------|-------------|
| `list_product_categories` | List categories with hierarchy |
| `create_product_category` | Create a category (with optional parent for subcategories) |
| `update_product_category` | Update category name, description, slug, parent |
| `delete_product_category` | Delete a category |

### Product Variations (5)
| Tool | Description |
|------|-------------|
| `list_product_variations` | List all variations for a variable product |
| `get_product_variation` | Full variation details (pricing, stock, attributes) |
| `create_product_variation` | Create a variation with attributes and pricing |
| `update_product_variation` | Update variation price, stock, status |
| `delete_product_variation` | Delete a variation |

### Product Attributes (5)
| Tool | Description |
|------|-------------|
| `list_product_attributes` | List all attributes (e.g. Color, Size) |
| `get_product_attribute` | Get attribute details with its terms |
| `create_product_attribute` | Create an attribute (select or text type) |
| `update_product_attribute` | Update attribute name, slug, ordering |
| `delete_product_attribute` | Delete an attribute from all products |

### Attribute Terms (4)
| Tool | Description |
|------|-------------|
| `list_attribute_terms` | List terms for an attribute (e.g. Red, Blue for Color) |
| `create_attribute_term` | Add a term to an attribute |
| `update_attribute_term` | Update a term's name, slug, description |
| `delete_attribute_term` | Delete a term |

### Product Tags (3)
| Tool | Description |
|------|-------------|
| `list_product_tags` | List tags with optional search |
| `create_product_tag` | Create a product tag |
| `delete_product_tag` | Delete a product tag |

### Product Reviews (4)
| Tool | Description |
|------|-------------|
| `list_product_reviews` | List reviews (filter by product or status) |
| `get_product_review` | Full review details |
| `create_product_review` | Create a review with rating |
| `delete_product_review` | Delete a review |

### Orders (10)
| Tool | Description |
|------|-------------|
| `list_orders` | List orders with filters (status, customer, date range) |
| `get_order` | Full order details (items, billing, shipping, payment) |
| `create_order` | Create an order with line items |
| `update_order_status` | Change order status (pending, processing, completed, etc.) |
| `update_order` | Edit order billing/shipping addresses and customer note |
| `delete_order` | Delete or trash an order |
| `list_order_notes` | Get all notes on an order |
| `create_order_note` | Add staff or customer-facing notes |
| `create_refund` | Issue a refund |
| `list_refunds` | List all refunds for an order |

### Customers (6)
| Tool | Description |
|------|-------------|
| `list_customers` | List customers with filters (role, search) |
| `get_customer` | Full customer details with addresses and order stats |
| `create_customer` | Create a new customer |
| `update_customer` | Update customer info, billing/shipping addresses |
| `delete_customer` | Delete a customer (with optional order reassignment) |
| `search_customers` | Search by name or email |

### Coupons (5)
| Tool | Description |
|------|-------------|
| `list_coupons` | List coupons with search |
| `get_coupon` | Full coupon details (restrictions, limits, usage) |
| `create_coupon` | Create percent, fixed cart, or fixed product coupons |
| `update_coupon` | Update coupon amount, expiry, limits, etc. |
| `delete_coupon` | Delete a coupon |

### Reports (4)
| Tool | Description |
|------|-------------|
| `get_sales_report` | Sales totals by period (week, month, year, custom range) |
| `get_top_sellers` | Top-selling products by period |
| `get_order_totals` | Order counts by status |
| `get_product_totals` | Product counts by type |

### Settings (1)
| Tool | Description |
|------|-------------|
| `get_store_settings` | Read store settings by group (general, products, tax, etc.) |

### Shipping & Payments (5)
| Tool | Description |
|------|-------------|
| `list_shipping_zones` | Shipping zones with their methods |
| `list_payment_gateways` | Payment gateways with enabled status |
| `list_tax_rates` | All configured tax rates |
| `list_tax_classes` | Tax classes (standard, reduced, zero rate) |
| `list_shipping_classes` | Product shipping classes |

### Webhooks (4)
| Tool | Description |
|------|-------------|
| `list_webhooks` | List all webhooks |
| `create_webhook` | Create webhooks for order/product/customer events |
| `update_webhook` | Update webhook URL, topic, status |
| `delete_webhook` | Delete a webhook |

### Batch Operations (2)
| Tool | Description |
|------|-------------|
| `batch_update_products` | Bulk update multiple products in one call |
| `batch_update_orders` | Bulk update multiple orders in one call |

### Data (2)
| Tool | Description |
|------|-------------|
| `list_currencies` | All supported currencies with codes and symbols |
| `list_countries` | All countries with states/provinces |

### System (1)
| Tool | Description |
|------|-------------|
| `get_system_status` | WooCommerce/WordPress versions, plugins, server environment |

## Authentication

WooCommerce uses **consumer key + consumer secret** for REST API auth. This server uses HTTP Basic Authentication over HTTPS.

1. Go to **WordPress Admin > WooCommerce > Settings > Advanced > REST API**
2. Click **Add key**
3. Set permissions to **Read/Write**
4. Copy the consumer key (`ck_...`) and consumer secret (`cs_...`)

> **Important:** Your store must use HTTPS for Basic Auth to work securely.

## Requirements

- Python 3.10+
- WooCommerce 3.5+ with REST API v3
- HTTPS enabled on your store

## License

MIT