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)

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

Order Creation & Management (9 tools)

Customer Management (7 tools)

Refunds & Tracking (3 tools)

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

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: support@alchemist.ai

License

MIT License - see LICENSE file for details.

Credits

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