MCP WooCommerce Server

A Model Context Protocol (MCP) server that provides tools to interact with WooCommerce REST API.

Features

Search Products: Search for products by name or SKU
List Products: Retrieve all products with pagination
Create Orders: Create new orders with line items
Get Orders: Retrieve specific orders by ID
List Orders: List orders with optional filters
🔐 Authentication: API Key-based authentication for secure access

Setup

Clone this repository

Copy .env.example to .env and fill in your WooCommerce API credentials:

WOO_URL=https://yourstore.com
WOO_CONSUMER_KEY=your_consumer_key
WOO_CONSUMER_SECRET=your_consumer_secret
MCP_API_KEY=your_secure_api_key_here

Get your WooCommerce API credentials:
- Go to WooCommerce > Settings > Advanced > REST API
- Create a new key with read/write permissions
- Copy the Consumer Key and Consumer Secret

Generate a secure API key for MCP authentication:

# Generate a random API key (Linux/Mac)
openssl rand -hex 32

# Or use Python
python -c "import secrets; print(secrets.token_hex(32))"

Security

Authentication

The server implements API Key authentication to protect against unauthorized access. When MCP_API_KEY is configured, all requests must include the API key in the Authorization header.

Without Authentication (Development Only)

If MCP_API_KEY is not set, the server runs without authentication for development purposes.

With Authentication (Production Recommended)

When MCP_API_KEY is set, clients must include:

Authorization: Bearer YOUR_API_KEY_HERE

Security Best Practices

Always set MCP_API_KEY in production environments
Use strong, randomly generated API keys (32+ characters)
Rotate API keys regularly
Use HTTPS in production
Limit network access to trusted sources only
Monitor access logs for suspicious activity

Running Locally

With Docker Compose

docker-compose up --build

The server will start on http://localhost:8200/mcp with modular architecture.

With Python

pip install -r requirements.txt
python -m src.server

Architecture

The project uses a modular architecture with the following structure:

src/server.py - FastAPI application with MCP integration and authentication
src/tools.py - MCP tools implementation (5 tools for WooCommerce operations)
src/config.py - Environment configuration and validation
src/woo_client.py - WooCommerce API client wrapper
src/models.py - Pydantic models for structured data
test/client_authenticated.py - Full-featured authenticated MCP client (recommended)
test/client_example.py - Basic MCP client using official libraries (limited auth support)
test/list_tools.py - Simple tool listing script

Client Compatibility Matrix

Component	With API Key (Production)	Without API Key (Development)	Notes
`test/client_authenticated.py`	✅ Fully Supported	❌ Requires API key	Recommended client with full auth support
Curl Scripts (`test/*.sh`)	✅ Fully Supported	❌ Requires API key	Manual testing with proper auth headers
`test/test_auth.sh`	✅ Fully Supported	❌ Requires API key	Authentication validation script
`test/list_tools.py`	❌ Limited support¹	✅ Works	Uses official MCP libraries
`test/client_example.py`	❌ Limited support¹	✅ Works	Uses official MCP libraries

¹ Limited support: May fail with authentication errors when API key is required

API Endpoints

The server exposes the following MCP tools:

search_products(query: str, per_page: int = 10) - Search products
list_products(per_page: int = 20, page: int = 1) - List all products
create_order(customer_id: int, line_items: List[Dict], billing: Dict, shipping: Optional[Dict]) - Create order
get_order(order_id: int) - Get specific order
list_orders(customer_id: Optional[int], status: Optional[str], per_page: int = 10) - List orders

WooCommerce API Requirements

WooCommerce 3.5+
WordPress 4.4+
Pretty permalinks enabled
REST API enabled (default)

Testing the MCP Server

Using the Example Clients

The project includes example MCP clients to test the server:

Authenticated Client (Recommended)

python test/client_authenticated.py

This is the recommended client for testing. It provides:

✅ Full API key authentication support
✅ Proper SSE response parsing
✅ Complete tool testing (list_products, search_products, etc.)
✅ Detailed output with product information
✅ Error handling and session management

Simple Tool Lister

python test/list_tools.py

This script connects to the MCP server and lists all available tools with their descriptions and parameters.

Basic Example Client (Limited)

python test/client_example.py

This client uses official MCP libraries but has limitations:

❌ Limited authentication support (may fail with API key auth)
❌ May encounter connection errors with authenticated servers
✅ Good for understanding MCP protocol structure

Testing Scripts

The project includes curl scripts for easy testing:

# Update the AUTH_HEADER in the scripts with your API key
# Then run:
./test/curl_list_products.sh
./test/curl_search_products.sh pulseras
./test/curl_create_order.sh

These scripts demonstrate proper authentication and SSE response handling.

Authentication Testing

# Run authentication tests
./test/test_auth.sh

This script validates that authentication is working correctly by testing different scenarios.

Data Ingestion Examples

The project includes example scripts for ingesting product data from the MCP server:

Bash Script (Recommended for Automation)

# Run the ingestion script
./ingestion_example.sh

This script demonstrates the correct format for MCP requests and handles SSE responses.

Python Script

# Activate virtual environment and run
source .venv/bin/activate
python ingestion_example.py

This Python client shows how to programmatically ingest data with proper error handling.

MCP Request Format

When building your own ingestion scripts, use this format to avoid 406 errors:

# 1. Initialize session (required)
curl -X POST http://localhost:8200/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "ingestion-client", "version": "1.0.0"}}}'

# 2. Call tools with session ID
curl -X POST http://localhost:8200/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "list_products", "arguments": {"per_page": 50}}}'

Important Headers:

Content-Type: application/json
Accept: application/json, text/event-stream
Authorization: Bearer YOUR_API_KEY
Mcp-Session-Id: YOUR_SESSION_ID (after initialization)