WooCommerce MCP Server (Full Lifecycle)

Custom WooCommerce MCP (Model Context Protocol) server with complete e-commerce lifecycle support.

Overview

This MCP server provides AI agents with access to WooCommerce store functionality through 36 tools covering the complete e-commerce lifecycle:

• Product Discovery: Search, browse categories, filter by price, reviews (17 tools)
• Orders & Management: Create orders directly with line items, track status, manage customers (19 tools)
• Post-Purchase: Refunds, returns, reviews, order history

Features

✅ 36 Complete Ecommerce Lifecycle Tools

Phase 1: Product Discovery (17 tools)

• Product search and listing
• Categories, tags, and attributes
• Product variations and details
• Customer reviews (list, get, update, submit)
• Shipping and payment information

Phase 2: Orders & Post-Purchase (19 tools)

• Order creation directly with line items (bypasses cart)
• Order tracking, search, and management
• Customer authentication, list, search, and profiles
• Payment link generation
• Refunds, returns, and reviews

Architecture

• Protocol: MCP JSON-RPC 2.0 over stdio
• API: WooCommerce REST API v3
• Authentication: HTTP Basic Auth (Consumer Key + Secret)
• State Management: Stateless (no cart sessions, orders created directly)
• Deployment: Compatible with OpenAI Responses API via mcp-service-template
• Language: Python 3.10+

Installation

Requirements

• Python 3.10 or higher
• Node.js 16+ (for npx deployment)
• WooCommerce 3.5+ with REST API enabled
• WooCommerce API Keys (Consumer Key + Consumer Secret)

Via NPM (Recommended)

npx -y @olbrain/woocommerce-mcp@latest

Local Development

cd mcp_servers/woocommerce-custom

# Install Python dependencies
pip install -r requirements.txt

# Run server directly
python3 src/server.py

Configuration

WooCommerce API Keys

1. Go to WordPress Admin → WooCommerce → Settings → Advanced → REST API
2. Click "Add key"
3. Description: "MCP Server"
4. User: Select admin user
5. Permissions: Read/Write
6. Click "Generate API key"
7. Copy Consumer Key (ck_...) and Consumer Secret (cs_...)

Environment Variables

The server requires these environment variables:

WOOCOMMERCE_STORE_URL=https://yourstore.com
CONSUMER_KEY=ck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
CONSUMER_SECRET=cs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Usage with mcp-service-template

The server is designed to be deployed via Alchemist's mcp-service-template:

1. User enables WooCommerce in project-dashboard
2. tool-manager syncs configuration to Firestore
3. deploy_job.py deploys mcp-service-template for agent
4. MCPManager spawns this server via npx @olbrain/woocommerce-mcp
5. OpenAI Responses API calls tools via JSON-RPC

Available Tools (36 Total)

Phase 1: Product Discovery (17 tools)

| Tool | Description | |------|-------------| | wc_search_products | Search products by keyword | | wc_list_products | List all products with pagination | | wc_get_product | Get detailed product information | | wc_get_categories | Get all product categories | | wc_get_category_products | Get products in a specific category | | wc_filter_products | Filter products by price, sale status, etc. | | wc_get_tags | Get all product tags | | wc_get_attributes | Get global product attributes | | wc_get_product_variations | Get all variations (sizes, colors) of a product | | wc_get_product_variation | Get specific variation details | | wc_get_related_products | Get related products by IDs | | wc_get_shipping_zones | Get all shipping zones | | wc_get_shipping_methods | Get shipping methods for a zone | | wc_get_payment_gateways | Get available payment methods | | wc_list_reviews | List all product reviews with filters | | wc_get_review | Get specific review by ID | | wc_update_review | Update review content or rating | | wc_submit_review | Submit product review |

Phase 2: Orders & Post-Purchase (19 tools)

Order Creation & Management (9 tools)

| Tool | Description | |------|-------------| | wc_create_order | Create new order with line items | | wc_get_order | Get complete order details | | wc_list_orders | List orders with filters | | wc_search_orders | Search orders by number/name/email | | wc_update_order | Update order status or notes | | wc_cancel_order | Cancel pending order | | wc_add_order_note | Add note to order | | wc_get_order_notes | Get all order notes | | wc_get_payment_link | Generate payment link for order |

Customer Management (7 tools)

| Tool | Description | |------|-------------| | wc_authenticate_customer | Login and get customer details | | wc_list_customers | List all customers with pagination | | wc_search_customers | Search customers by name or email | | wc_get_customer | Get customer profile | | wc_update_customer | Update customer information | | wc_get_customer_orders | Get customer order history | | wc_get_customer_downloads | Get downloadable products |

Refunds & Tracking (3 tools)

| Tool | Description | |------|-------------| | wc_create_refund | Process order refund | | wc_get_order_refunds | List refunds for order | | wc_get_tracking_info | Get shipment tracking details |

Testing

Local stdio Test

# Start server
python3 src/server.py

# Send JSON-RPC request (in another terminal)
echo '{"jsonrpc":"2.0","method":"tools/list","id":1,"params":{}}' | python3 src/server.py

With OpenAI Responses API

from openai import AsyncOpenAI

client = AsyncOpenAI()

response = await client.responses.create(
    model="gpt-5-mini",
    input="Find sleep tea products",
    tools=[{
        "type": "mcp",
        "server_url": "https://mcp-ea65a288-xxx.run.app/",
        "require_approval": "never",
        "allowed_tools": ["wc_search_products", "wc_get_product"]
    }]
)

Development

Project Structure

woocommerce-custom/
├── server_config.json          # Alchemist MCP server configuration
├── README.md                   # This file
├── package.json                # npm package metadata
├── index.js                    # Node.js stdio launcher
├── requirements.txt            # Python dependencies
├── src/
│   ├── server.py               # MCP server main (JSON-RPC 2.0)
│   ├── woocommerce_client.py   # WooCommerce REST API v3 client
│   └── tools/
│       ├── product_tools.py    # 15 product discovery tools
│       └── order_tools.py      # 20 order & customer tools

Adding New Tools

1. Choose the appropriate tools file (product_tools.py or order_tools.py)

2. Add tool definition to the tools list:

   {
       "name": "wc_new_tool",
       "description": "Tool description",
       "inputSchema": {
           "type": "object",
           "properties": {...}
       }
   }

3. Implement tool handler:

   async def wc_new_tool(wc_client, arguments: Dict[str, Any]) -> Dict[str, Any]:
       # All tools use WooCommerce REST API v3
       result = await wc_client.get("/endpoint", params=arguments)
       return {"data": result}

4. Register in the tool handlers dict at the bottom of the file

Comparison: Third-Party vs Custom

| Aspect | Third-Party | Custom (This) | |--------|-------------|---------------| | Tools | 17 (basic lifecycle) | 36 (complete lifecycle) ✅ | | Auth | JWT token | API Keys (Consumer Key/Secret) | | Coverage | Discovery, reviews | Discovery + Orders + Reviews + Post-Purchase | | Customization | None | Full control | | API | WordPress Remote | WooCommerce REST API v3 | | Cart | ❌ Not supported | ✅ Direct order creation (bypasses cart) | | Orders | ✅ Basic (7 tools) | ✅ Enhanced (19 tools) | | Reviews | ✅ Basic (4 tools) | ✅ Complete (4 tools) | | Lifecycle | Basic coverage | Complete end-to-end | | Parity | Baseline | 100% + 19 enhanced tools |

Implementation Status

✅ Phase 1: Product Discovery (COMPLETE) - 17 tools

• Product search, categories, variations, reviews (list, get, update, submit)

✅ Phase 2: Orders & Post-Purchase (COMPLETE) - 19 tools

• Order creation with line items (bypasses cart), search, tracking
• Payment link generation, shipment tracking
• Customer list, search, authentication, and management
• Refunds and tracking

✅ Full Parity with Existing Tools - 17/17 tools ✅

• All tools from alchemist-public-tools/tools/woocommerce implemented
• Additional 19 enhanced tools for complete coverage
• Non-functional cart-based checkout tools removed for stateless architecture

🔜 Phase 3: Advanced Features (Future)

• Inventory management and stock alerts
• Analytics and reporting dashboards
• Real-time webhooks for notifications
• Subscription management
• Multi-currency support

Support

• Documentation: https://woocommerce.github.io/woocommerce-rest-api-docs/
• Issues: https://github.com/alchemist-ai/alchemist-public-tools/issues
• Email: [email protected]

License

MIT License - see LICENSE file for details.

Credits

Built by Alchemist for the Model Context Protocol (MCP) ecosystem.