npm package: @olbrain/woocommerce-mcp
Description: WooCommerce MCP Server with full e-commerce lifecycle support
Author: Alchemist
Latest version: 1.0.0

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

```bash
npx -y @olbrain/woocommerce-mcp@latest
```

### Local Development

```bash
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:

```bash
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

```bash
# 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

```python
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:
   ```python
   {
       "name": "wc_new_tool",
       "description": "Tool description",
       "inputSchema": {
           "type": "object",
           "properties": {...}
       }
   }
   ```

3. Implement tool handler:
   ```python
   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**: support@alchemist.ai

## License

MIT License - see LICENSE file for details.

## Credits

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