DEV Community

Alex LaGuardia
Alex LaGuardia

Posted on

Managing a WooCommerce Store from Claude — 34 MCP Tools I Wish Existed

#mcp #ai #python #woocommerce

WooCommerce runs 36% of all online stores — over 5 million active sites. If you're using Claude or Cursor and want to check orders, update products, or pull sales reports, you're copy-pasting from WordPress admin like it's 2015.

I built 34 MCP tools that let your AI assistant manage a WooCommerce store directly. Products, orders, customers, coupons, shipping, reports — full CRUD, not just read-only.

What It Does

MCP lets AI assistants interact with external tools directly. With this server installed, you stop tab-switching between Claude and your WordPress admin panel.

Before (manual):

  1. Open WordPress admin
  2. Navigate to WooCommerce → Orders
  3. Filter by date range
  4. Export or copy the data
  5. Paste into Claude
  6. Ask for analysis

After (with mcp-woocommerce):

"Show me all orders from this week. Which products are selling best and what's my average order value?"

Claude calls list_orders, then get_sales_report, and gives you the analysis — all in one conversation.

34 Tools, Full CRUD

Not just reading data — you can manage your entire store:

  • Products (7): List, get, create, update, delete, manage variations, batch operations
  • Orders (5): List, get, create, update, add notes
  • Customers (4): List, get, create, update with full address support
  • Coupons (3): List, get, create with discount types and usage limits
  • Reports (4): Sales, top sellers, orders totals, and customer totals
  • Shipping (3): Zones, methods, and zone-method configuration
  • Webhooks (3): List, create, delete for real-time event handling
  • Payments (2): List gateways and toggle enable/disable
  • System (3): Store info, status checks, and settings

Technical Decisions Worth Sharing

URL Normalization

WooCommerce's REST API lives at /wp-json/wc/v3 under whatever domain the store uses. Users will pass in mystore.com, https://mystore.com, or https://mystore.com/wp-json/wc/v3. The client handles all of them:

base = store_url.rstrip("/")
if not base.startswith(("https://", "http://")):
    base = f"https://{base}"
if not base.endswith("/wp-json/wc/v3"):
    base = f"{base}/wp-json/wc/v3"
Enter fullscreen mode Exit fullscreen mode

One less thing for users to get wrong.

HTTP Basic Auth (The Simple Kind)

WooCommerce uses consumer key/secret pairs over HTTPS — no OAuth dance, no token refresh, no expiration headaches. You generate keys in WordPress admin (WooCommerce → Settings → Advanced → REST API), set the permission level (read, write, or read/write), and you're done.

self._client = httpx.AsyncClient(
    base_url=self.base_url,
    auth=(consumer_key, consumer_secret),
    follow_redirects=True,
)
Enter fullscreen mode Exit fullscreen mode

The follow_redirects=True is important — many WordPress installs have redirect rules (www ↔ non-www, HTTP → HTTPS) that will silently break API calls without it.

Array Responses vs Object Responses

Unlike most APIs that wrap results in {"data": [...], "total": N}, WooCommerce returns bare arrays for list endpoints. Pagination info comes in response headers (X-WP-Total, X-WP-TotalPages), not the body. Every tool handles this:

data = await wc.get("/products", params=params)
products = []
for p in data if isinstance(data, list) else []:
    products.append({...})
return _fmt({"count": len(products), "products": products})
Enter fullscreen mode Exit fullscreen mode

The AI gets a consistent format regardless of WooCommerce's quirks.

Structured Error Codes

WooCommerce returns machine-readable error codes (woocommerce_rest_product_invalid_id, woocommerce_rest_cannot_view) alongside human messages. The client preserves both:

raise WooCommerceError(
    data.get("code", "unknown_error"),
    data.get("message", "No details provided"),
    resp.status_code,
)
Enter fullscreen mode Exit fullscreen mode

When the AI hits an error, it gets enough context to explain what went wrong and suggest a fix — not just "400 Bad Request."

Get Started in 2 Minutes

Install 

pip install mcp-woocommerce
Enter fullscreen mode Exit fullscreen mode

Generate API Keys

WordPress Admin → WooCommerce → Settings → Advanced → REST API → Add Key.

Set permissions to Read/Write and save the consumer key and secret.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "woocommerce": {
      "command": "mcp-woocommerce",
      "env": {
        "WOOCOMMERCE_URL": "https://yourstore.com",
        "WOOCOMMERCE_KEY": "ck_your_key",
        "WOOCOMMERCE_SECRET": "cs_your_secret"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Claude Code 

claude mcp add woocommerce -- env WOOCOMMERCE_URL=https://yourstore.com WOOCOMMERCE_KEY=ck_key WOOCOMMERCE_SECRET=cs_secret mcp-woocommerce
Enter fullscreen mode Exit fullscreen mode

Cursor

Same JSON config as Claude Desktop in .cursor/mcp.json.

What I'd Do Differently

Add batch endpoints sooner. WooCommerce supports batch create/update/delete for products, orders, and coupons in a single API call. I added product batch operations but should have done it across all resources from the start — it's a massive time saver for bulk operations.

Test with a staging store. WooCommerce's behavior varies wildly depending on installed plugins, theme, and WordPress version. A clean WooCommerce install acts differently from one running 30 plugins with custom REST API filters.

Lessons for MCP Server Builders

  1. Handle URL normalization. Don't assume users will pass the exact base URL your client expects. Accept the most natural input and normalize it.
  2. Follow redirects. WordPress sites love redirects. If your HTTP client doesn't follow them, you'll get mysterious failures.
  3. Normalize response shapes. If the API returns arrays sometimes and objects other times, your tools should present a consistent format to the AI.
  4. Preserve error codes. Machine-readable error codes help the AI reason about failures and suggest fixes. Don't throw them away.

Links

This is part of a series of production-grade MCP servers I'm building for underserved SaaS platforms. Also available: Mailchimp, FreshBooks, ActiveCampaign. Follow me here or on GitHub to catch the next one.

Top comments (0)