mcp-server-woocommerce

MCP server for managing WooCommerce stores through AI assistants like Claude. Provides 82 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:

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

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

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

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, and coupons 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 82 tools for safe agent behavior
• Actionable errors — error responses include guidance on how to fix common issues

Available Tools (82)

Resources

The server exposes 5 MCP resources that provide schema references and guides for AI agents:

Resources are read-only context that agents can fetch to understand WooCommerce data structures before making API calls.

Prompts

3 guided workflow prompts that orchestrate multi-step operations:

Tool Annotations

Every tool is annotated with behavior hints so AI agents can make safe decisions:

All tools also set openWorldHint: false — they only interact with WooCommerce, no external side effects.

Configuration

Environment Variables

Using a .env file

Instead of inlining credentials, point to a directory with a .env file:

{
  "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:

{
  "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:

# 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.

Agent Orchestration

This project is maintained by a team of AI agents coordinated via Paperclip. See docs/ORCHESTRATION.md for details.

Development

git clone https://github.com/AmitGurbani/mcp-server-woocommerce.git
cd mcp-server-woocommerce
pnpm install

pnpm dev          # Watch mode
pnpm build        # Build
pnpm start        # Run directly
pnpm test         # Run tests
pnpm test:watch   # Run tests in watch mode
pnpm inspector    # Debug with MCP Inspector

Docker

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

License

MIT

WooCommerce is a registered trademark of Automattic Inc. This project is not affiliated with, endorsed by, or sponsored by Automattic Inc.