woocommerce-mcp-server by lord-dubious - MCP Server

WooCommerce MCP Server

A Model Context Protocol (MCP) server for WooCommerce integration, providing AI agents and Claude with tools to manage WooCommerce stores.

What Changed

This server has been completely rewritten to properly implement the MCP standard:

Before (Issues)

❌ Custom JSON-RPC implementation instead of MCP SDK
❌ No proper MCP protocol support (initialization, capabilities, etc.)
❌ Custom readline-based transport
❌ Massive switch statement with 100+ cases
❌ No input validation or proper error handling
❌ Not compatible with MCP clients like Claude Desktop

After (Fixed)

✅ Uses official MCP TypeScript SDK (@modelcontextprotocol/sdk)
✅ Proper MCP protocol implementation with capabilities
✅ Standard stdio transport for MCP clients
✅ Clean tool-based architecture with proper schemas
✅ Zod validation for all inputs
✅ Proper error handling and user-friendly responses
✅ Compatible with Claude Desktop and other MCP clients

Features

📦 Product Management

get_products - Retrieve products with filtering options
get_product - Get specific product by ID
create_product - Create new products
update_product - Update existing products
delete_product - Delete products

📋 Order Management

get_orders - Retrieve orders with filtering
get_order - Get specific order by ID
create_order - Create new orders
update_order - Update existing orders
delete_order - Delete orders

👥 Customer Management

get_customers - Retrieve customers
get_customer - Get specific customer by ID
create_customer - Create new customers
update_customer - Update existing customers
delete_customer - Delete customers

🎫 Coupon Management

get_coupons - Retrieve coupons with filtering
get_coupon - Get specific coupon by ID
create_coupon - Create new coupons
update_coupon - Update existing coupons
delete_coupon - Delete coupons

🔧 Product Attributes

get_product_attributes - Retrieve product attributes
get_product_attribute - Get specific attribute by ID
create_product_attribute - Create new attributes
update_product_attribute - Update existing attributes
delete_product_attribute - Delete attributes

🔄 Product Variations

get_product_variations - Retrieve variations for variable products
get_product_variation - Get specific variation by ID
create_product_variation - Create new product variations
update_product_variation - Update existing variations
delete_product_variation - Delete variations

📝 Order Notes

get_order_notes - Retrieve notes for orders
get_order_note - Get specific order note
create_order_note - Add notes to orders
delete_order_note - Delete order notes

💰 Order Refunds

get_order_refunds - Retrieve refunds for orders
get_order_refund - Get specific refund details
create_order_refund - Process order refunds
delete_order_refund - Delete refunds

📊 Reports & Analytics

get_sales_report - Get sales data and analytics
get_products_report - Get products performance report
get_orders_report - Get orders analytics report
get_customers_report - Get customers analytics report
get_categories_report - Get categories performance report
get_stock_report - Get stock levels report
get_coupons_report - Get coupons usage report
get_taxes_report - Get taxes report

💳 Payment Gateways

get_payment_gateways - Retrieve all payment gateways
get_payment_gateway - Get specific payment gateway
update_payment_gateway - Update payment gateway settings

🔗 Meta Data Operations

get_product_meta - Retrieve product meta data
set_product_meta - Set (create/update) product meta data
delete_product_meta - Delete product meta data
get_order_meta - Retrieve order meta data
set_order_meta - Set (create/update) order meta data
delete_order_meta - Delete order meta data
get_customer_meta - Retrieve customer meta data
set_customer_meta - Set (create/update) customer meta data
delete_customer_meta - Delete customer meta data

⭐ Product Reviews

get_product_reviews - Retrieve product reviews
get_product_review - Get specific review by ID
create_product_review - Create new product review
update_product_review - Update existing review
delete_product_review - Delete review

⚙️ Settings Management

get_settings - Retrieve WooCommerce settings groups
get_setting_options - Get options for specific settings group
update_setting_option - Update specific setting options

🌍 Data & Geography

get_data - Retrieve general WooCommerce data
get_continents - Get continents and their countries
get_countries - Get a list of countries
get_currencies - Get available currencies
get_current_currency - Get current currency information

📄 WordPress Posts Management

create_post - Create new WordPress posts
get_posts - Retrieve WordPress posts
update_post - Update existing posts
get_post_meta - Get WordPress post meta data

⚙️ System Information

get_system_status - Get WooCommerce system status and diagnostics
get_system_status_tools - Get available system status tools
run_system_status_tool - Execute system status tools

Installation

Clone the repository:

git clone https://github.com/lord-dubious/woocommerce-mcp-server.git
cd woocommerce-mcp-server

Install dependencies:

npm install

Build the project:

npm run build

Configuration

Set up your environment variables in a .env file:

# Required for WooCommerce API
WORDPRESS_SITE_URL=https://your-site.com
WOOCOMMERCE_CONSUMER_KEY=ck_your_consumer_key
WOOCOMMERCE_CONSUMER_SECRET=cs_your_consumer_secret

# Optional for WordPress API (if needed)
WORDPRESS_USERNAME=your_username
WORDPRESS_PASSWORD=your_password

Getting WooCommerce API Keys

Go to your WordPress admin dashboard
Navigate to WooCommerce > Settings > Advanced > REST API
Click Add Key
Set permissions to Read/Write
Copy the Consumer Key and Consumer Secret

Usage

With Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "woocommerce": {
      "command": "node",
      "args": ["/path/to/woocommerce-mcp-server/build/index.js"],
      "env": {
        "WORDPRESS_SITE_URL": "https://your-site.com",
        "WOOCOMMERCE_CONSUMER_KEY": "ck_your_key",
        "WOOCOMMERCE_CONSUMER_SECRET": "cs_your_secret"
      }
    }
  }
}

Command Line Testing

You can test the server directly:

npm start

Then send MCP messages via stdin (for debugging).

Example Usage in Claude

Once configured, you can ask Claude to:

"Show me the latest 10 products from my WooCommerce store"
"Create a new product called 'Test Product' with price $29.99"
"Get the details of order #123"
"Show me this month's sales report"
"List all customers who signed up this week"
"Create a 20% off coupon for electronics"
"Add a note to order #456"
"Process a refund for order #789"
"Get all variations for product #123"

Tool Parameters

Credentials (Optional for all tools)

You can override environment variables per request:

{
  credentials: {
    siteUrl: "https://different-site.com",
    consumerKey: "different_key",
    consumerSecret: "different_secret"
  }
}

Product Tools

get_products: perPage, page, search, category, tag, featured, on_sale, min_price, max_price, stock_status
get_product: productId
create_product: productData (name, type, regular_price, description, etc.)
update_product: productId, productData
delete_product: productId, force

Order Tools

get_orders: perPage, page, search, after, before, status, customer, product
get_order: orderId
create_order: orderData (billing, shipping, line_items, etc.)
update_order: orderId, orderData
delete_order: orderId, force

Customer Tools

get_customers: perPage, page, search, email, role
get_customer: customerId
create_customer: customerData (email, first_name, last_name, billing, shipping)
update_customer: customerId, customerData
delete_customer: customerId, force, reassign

Category Tools

get_product_categories: perPage, page, search, parent, hide_empty
get_product_category: categoryId
create_product_category: categoryData (name, slug, parent, description, etc.)
update_product_category: categoryId, categoryData
delete_product_category: categoryId, force

Tag Tools

get_product_tags: perPage, page, search, hide_empty
get_product_tag: tagId
create_product_tag: tagData (name, slug, description)
update_product_tag: tagId, tagData
delete_product_tag: tagId, force

Coupon Tools

get_coupons: perPage, page, search, after, before, code
get_coupon: couponId
create_coupon: couponData (code, amount, discount_type, etc.)
update_coupon: couponId, couponData
delete_coupon: couponId, force

Attribute Tools

get_product_attributes: perPage, page
get_product_attribute: attributeId
create_product_attribute: attributeData (name, slug, type, etc.)
update_product_attribute: attributeId, attributeData
delete_product_attribute: attributeId, force

Report Tools

get_sales_report: period, date_min, date_max
get_products_report: period, date_min, date_max, perPage, page
get_orders_report: period, date_min, date_max, perPage, page
get_customers_report: perPage, page

Payment Gateway Tools

get_payment_gateways: No parameters
get_payment_gateway: gatewayId
update_payment_gateway: gatewayId, gatewayData (enabled, title, description, settings)

Error Handling

The server provides detailed error messages for:

Missing credentials
Invalid API responses
Network errors
Validation errors

All errors are returned in a user-friendly format with context.

Development

Adding New Tools

Define input schema with Zod
Register tool with server.registerTool()
Implement async handler function
Add proper error handling
Update documentation

Testing

The server includes a comprehensive testing system to validate all tools and functionality.

Quick Test (Schema Validation)

npm test

This runs basic schema validation tests without requiring WooCommerce credentials.

Full API Testing

# Set up test credentials
export TEST_WORDPRESS_SITE_URL='https://your-test-site.com'
export TEST_WOOCOMMERCE_CONSUMER_KEY='ck_your_test_key'
export TEST_WOOCOMMERCE_CONSUMER_SECRET='cs_your_test_secret'

# Run full API tests
npm run test

Advanced Testing

npm run test:full  # Run comprehensive MCP server tests
npm run validate   # Validate build and schemas only

Test Configuration

Copy tests/test-config.example.env to .env and configure your test credentials:

TEST_WORDPRESS_SITE_URL=https://your-test-site.com
TEST_WOOCOMMERCE_CONSUMER_KEY=ck_your_test_key
TEST_WOOCOMMERCE_CONSUMER_SECRET=cs_your_test_secret

⚠️ Important: Always use a test/staging site, never your production store!

What Gets Tested

✅ All 91 WooCommerce tools
✅ Schema validation for all data types
✅ Error handling and edge cases
✅ API connectivity and authentication
✅ Response format validation
✅ Performance metrics

License

MIT License - see LICENSE file for details.

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

Support

For issues and questions:

Open an issue on GitHub
Check WooCommerce REST API documentation
Review MCP specification

lord-dubious/woocommerce-mcp-server

get_products

create_product

get_orders

create_order

get_customers