Content
# mcp-woocommerce
[](https://python.org)
[](LICENSE)
[](https://modelcontextprotocol.io)
**MCP server for WooCommerce store management.** Gives Claude direct access to your store — list products, audit quality issues, update descriptions and categories, and delete duplicates. No more writing scripts or parsing curl output.
---
## What it does
| Tool | Description |
|---|---|
| `list_products` | List products with filters (category, search, status, pagination) |
| `get_product` | Full details of a product: images, description, categories, price |
| `update_product` | Update any field: title, description, price, categories, images |
| `delete_product` | Delete or trash a product |
| `batch_update_products` | Update multiple products in a single API call |
| `list_categories` | All categories with IDs and slugs |
| `audit_products` | Scan the store for issues: ghost images, short descriptions, wrong categories, price 0 |
The `audit_products` tool detects:
- Descriptions under 100 characters
- More than 7 images per product
- Main product image is a Printful ghost/placeholder (no design visible)
- Price set to 0
- Products with no category
- Wrong category mixes (e.g. a children's product also tagged as adult)
---
## Installation
### Using uvx (recommended — no install needed)
```bash
# Run directly from PyPI
uvx mcp-woocommerce
# Or from GitHub
uvx --from git+https://github.com/cr0hn/mcp-woocommerce mcp-woocommerce
```
### Using uv
```bash
uv tool install mcp-woocommerce
# Or from GitHub
uv tool install git+https://github.com/cr0hn/mcp-woocommerce
```
### Using pip
```bash
pip install mcp-woocommerce
```
---
## Configuration
Three environment variables are required:
| Variable | Description | Example |
|---|---|---|
| `WOOCOMMERCE_URL` | Your store's base URL | `https://mystore.com` |
| `WOOCOMMERCE_CONSUMER_KEY` | WooCommerce REST API consumer key | `ck_abc123...` |
| `WOOCOMMERCE_CONSUMER_SECRET` | WooCommerce REST API consumer secret | `cs_xyz789...` |
### Generating API keys
1. Go to **WooCommerce → Settings → Advanced → REST API**
2. Click **Add key**
3. Set permissions to **Read/Write**
4. Copy the consumer key and secret (they are only shown once)
---
## Claude Desktop setup
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"woocommerce": {
"command": "uvx",
"args": ["mcp-woocommerce"],
"env": {
"WOOCOMMERCE_URL": "https://mystore.com",
"WOOCOMMERCE_CONSUMER_KEY": "ck_...",
"WOOCOMMERCE_CONSUMER_SECRET": "cs_..."
}
}
}
}
```
Or if running from GitHub before PyPI publication:
```json
{
"mcpServers": {
"woocommerce": {
"command": "uvx",
"args": ["--from", "git+https://github.com/cr0hn/mcp-woocommerce", "mcp-woocommerce"],
"env": {
"WOOCOMMERCE_URL": "https://mystore.com",
"WOOCOMMERCE_CONSUMER_KEY": "ck_...",
"WOOCOMMERCE_CONSUMER_SECRET": "cs_..."
}
}
}
}
```
### Claude Code (via CLI)
```bash
claude mcp add woocommerce \
--command uvx \
--args mcp-woocommerce \
-e WOOCOMMERCE_URL=https://mystore.com \
-e WOOCOMMERCE_CONSUMER_KEY=ck_... \
-e WOOCOMMERCE_CONSUMER_SECRET=cs_...
```
---
## Tool reference
### `list_products`
```
per_page int Products per page (default 20, max 100)
page int Page number (default 1)
search str Search term
category_id int Filter by category ID
status str publish | draft | pending | private | any (default: publish)
```
Returns a list with `id`, `name`, `price`, `categories`, `image_count`, `description_length`.
### `get_product`
```
product_id int WooCommerce product ID
```
Returns full product details including all images and the full description text.
### `update_product`
```
product_id int Product to update
name str New title
description str New description (HTML allowed)
short_description str New short description
regular_price str New price, e.g. "14.00"
status str publish | draft | private
category_ids list[int] Category IDs to assign (replaces existing)
image_ids list[int] Image IDs to keep (replaces existing list)
```
Only provided fields are updated. All others remain unchanged.
### `delete_product`
```
product_id int Product to delete
force bool True = permanent delete, False = move to trash (default False)
```
### `batch_update_products`
```
updates list[dict] Each dict needs 'id' + fields to update
```
Example:
```json
[
{"id": 123, "description": "<p>New text</p>", "categories": [{"id": 16}]},
{"id": 456, "regular_price": "19.00"}
]
```
### `list_categories`
```
per_page int Max categories to return (default 100)
```
Returns `id`, `name`, `slug`, `count`, `parent` for each category.
### `audit_products`
```
per_page int Products to audit per request (default 100)
fix_images bool Auto-fix: remove ghost images, cap at 7 (default False)
fix_categories bool Auto-fix: remove forbidden category mixes (default False)
```
Returns:
```json
{
"total_products": 40,
"ok": 38,
"with_issues": 2,
"fixes_applied": 0,
"issues": [
{
"id": 123,
"name": "Product Name",
"issues": ["description too short (45 chars, min 100)", "too many images (22, max 7)"]
}
]
}
```
---
## Development
```bash
git clone https://github.com/cr0hn/mcp-woocommerce
cd mcp-woocommerce
uv sync --all-groups
uv run pytest
```
Run the server locally:
```bash
WOOCOMMERCE_URL=https://mystore.com \
WOOCOMMERCE_CONSUMER_KEY=ck_... \
WOOCOMMERCE_CONSUMER_SECRET=cs_... \
uv run mcp-woocommerce
```
---
## License
MIT — see [LICENSE](LICENSE).
