MCP WooCommerce Server

MCP WooCommerce Server v2.4.0 - N8N Compatible

🚀 Complete MCP (Model Context Protocol) Server for WooCommerce Integration

Production-Ready | Real Data Integration | EasyPanel Deployment | N8N Automation Support | Schema Compatible

✨ Project Overview

Name: MCP WooCommerce Server
Version: v2.4.0
Goal: Complete WooCommerce e-commerce automation through MCP protocol
Features: 44+ comprehensive WooCommerce API tools with bidirectional MCP communication
N8N Compatible: Specialized endpoints for N8N workflow automation

🌍 Live URLs

Production: Ready for EasyPanel deployment
GitHub: https://github.com/Marckello/mcp_woo_marckello
MCP Protocol: Native MCP with WebSocket & SSE support
N8N Endpoints: /n8n/tools and /n8n/execute for workflow automation

🆕 N8N Integration (NEW v2.4.0)

🚨 SOLVED: N8N Schema Compatibility Errors

If you're getting "Received tool input did not match expected schema" errors in N8N, use these specialized N8N endpoints:

N8N-Compatible Endpoints:

GET /n8n/tools - Get available tools in N8N-compatible format
POST /n8n/execute - Execute tools with N8N schema validation

Example N8N Request:

POST /n8n/execute
{
  "toolName": "wc_get_coupon_stats",
  "input": {
    "coupon_code": "holasalud"
  }
}

N8N Response Format:

{
  "content": [
    {
      "type": "text",
      "text": "{\"success\": true, \"data\": {...}}"
    }
  ],
  "isError": false
}

📋 Full N8N Integration Guide: See N8N_INTEGRATION.md

🏗️ Technical Architecture

Core Technologies

Framework: TypeScript + Node.js + Express
Protocol: MCP (Model Context Protocol) with JSON-RPC 2.0
Transport: HTTP + WebSocket + Server-Sent Events (SSE)
API Integration: WooCommerce REST API v3
N8N Compatibility: Schema validation layer for workflow automation
Deployment: Docker multi-stage builds for EasyPanel
Automation: N8n workflow integration with dedicated endpoints

Data Architecture

WooCommerce API: Real-time data integration (no demo data)
Storage Services: Direct WooCommerce database connection
Customer Analytics: Hybrid system (registered + guest customers)
Revenue Calculations: Matches WooCommerce Dashboard methodology
Timezone: Mexico City (UTC-6) support

Security & Validation

Authentication: WooCommerce OAuth credentials
Validation: Joi schemas for all API inputs
N8N Compatibility: Input sanitization and schema validation
Security: Helmet + CORS middleware
Logging: Winston structured logging
Error Handling: Comprehensive error management

🛠️ MCP Tools Available (44+ Tools)

✅ Analytics & Reports (VERIFIED)

wc_get_revenue_stats - Revenue statistics ($122,351.67 gross revenue ✅)
wc_get_order_stats - Order analytics (50 orders, 35 completed ✅)
wc_get_customer_analytics - Customer insights (50 customers, LTV $2,758.45 ✅)
wc_get_coupon_stats - Coupon performance (holasalud: 12 orders, $52,477.20 ✅)
wc_get_refund_stats - Refund analysis
wc_get_tax_reports - Tax reporting

✅ Customer Management (VERIFIED)

wc_get_customers - Customer listing ✅
wc_get_customer - Individual customer details ✅
wc_get_top_customers - Top spenders (María Flor: $21,416.80 ✅)
wc_get_customer_analytics - Customer LTV and segmentation ✅
wc_get_customer_purchase_history - Purchase patterns
wc_create_customer - New customer creation
wc_update_customer - Customer updates
wc_delete_customer - Customer removal

✅ Coupon Management (VERIFIED)

wc_get_coupons - Coupon listing ✅
wc_get_coupon - Individual coupon details ✅
wc_get_coupon_by_code - Find by coupon code ✅
wc_get_coupon_usage_stats - Usage analytics (5 coupons, 12 uses ✅)
wc_get_top_coupons_usage - Most used coupons
wc_create_coupon - New coupon creation
wc_update_coupon - Coupon updates
wc_delete_coupon - Coupon removal

Product Management

wc_get_products - Product catalog
wc_get_product - Product details
wc_create_product - Product creation
wc_update_product - Product updates
wc_delete_product - Product removal
wc_batch_products - Bulk operations

Order Management

wc_get_orders - Order listing
wc_get_order - Order details
wc_create_order - Order creation
wc_update_order - Order updates
wc_delete_order - Order removal

📊 Verified Real Data Results

Revenue Analytics

Gross Revenue: $122,351.67
Net Revenue: $119,844.25
Shipping Revenue: $10,995.12
Discounts Given: $2,507.42

Customer Insights

Total Customers: 50 (registered + guest)
Returning Customers: 18 (36%)
VIP Customers: 1
Average LTV: $2,758.45

Top Customer

Name: María Flor
Email: correo@correo.com
Total Spent: $21,416.80
Orders: 2

Coupon Performance (holasalud)

Usage Count: 12 orders
Total Discount: $5,830.78
Net Revenue Generated: $52,477.20
Average Order Value: $4,373.10

🚀 Deployment Guide

EasyPanel Deployment

# 1. Configure Cloudflare API (if needed)
npm run setup:cloudflare

# 2. Set environment variables in EasyPanel
WOOCOMMERCE_URL=https://your-store.com
WOOCOMMERCE_KEY=ck_your_consumer_key
WOOCOMMERCE_SECRET=cs_your_consumer_secret
NODE_ENV=production
PORT=3001

# 3. Deploy with Docker
docker build -t mcp-woocommerce-server .

Local Development

# 1. Install dependencies
npm install

# 2. Configure environment
cp .env.example .env
# Edit .env with your WooCommerce credentials

# 3. Build and start
npm run build
npm start

# 4. Test MCP endpoints
curl http://localhost:3001/health
curl http://localhost:3001/mcp -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# 5. Test N8N endpoints
curl http://localhost:3001/n8n/tools

🔌 MCP Protocol Integration

Connection Methods

HTTP: POST http://localhost:3001/mcp
WebSocket: ws://localhost:3001/mcp-ws
Server-Sent Events: http://localhost:3001/mcp-sse
N8N Compatible: POST http://localhost:3001/n8n/execute

Example MCP Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "wc_get_revenue_stats",
    "arguments": {
      "period": "month",
      "timezone": "America/Mexico_City"
    }
  }
}

Example N8N Request

{
  "toolName": "wc_get_revenue_stats",
  "input": {
    "period": "month",
    "timezone": "America/Mexico_City"
  }
}

🔄 N8n Automation Integration

Standard Webhook Endpoint

URL: http://localhost:3001/webhook/n8n
Method: POST
Content-Type: application/json

N8N-Compatible Tool Endpoints

Tools List: GET http://localhost:3001/n8n/tools
Execute Tool: POST http://localhost:3001/n8n/execute

Integration Features

Schema-validated tool execution
Real-time order notifications
Customer lifecycle automation
Inventory management triggers
Revenue tracking workflows

🛡️ Security & Best Practices

Production Configuration

✅ Environment variables for credentials
✅ Input validation with Joi schemas
✅ N8N schema compatibility layer
✅ Rate limiting and security headers
✅ Structured logging for monitoring
✅ Error handling and recovery
✅ Docker multi-stage builds

API Rate Limits

WooCommerce API: 50 requests per page (optimized)
MCP Protocol: No artificial limits
N8N Endpoints: Validated input processing
Error recovery: Automatic retry logic

📋 Recent Updates (v2.4.0)

🔥 Major N8N Compatibility Update

✅ N8N Schema Compatibility - Complete solution for "tool input did not match expected schema" errors
✅ Dedicated N8N Endpoints - /n8n/tools and /n8n/execute for seamless integration
✅ Input Validation Layer - Sanitization and validation for N8N workflow compatibility
✅ Enhanced Error Handling - N8N-specific error responses and recovery

🔧 Critical Fixes Applied (v2.3.0)

✅ Complete demo data elimination - Only real WooCommerce data returned
✅ Revenue calculation fix - Now matches WooCommerce Dashboard exactly
✅ Guest customer support - Includes non-registered customers in analytics
✅ Routing corrections - All tools route to correct handlers
✅ API limit optimization - Fixed per_page limits for better performance

🚀 New Features

✅ N8N Workflow Integration - Native support for N8N automation
✅ Hybrid customer analytics - Registered + guest customer insights
✅ Enhanced coupon analytics - Usage patterns and revenue impact
✅ Real-time data validation - All responses verified against live data
✅ Mexico City timezone - Proper UTC-6 handling

🏆 Production Verification

All critical tools tested with real production data:

✅ Revenue Stats: $122K+ verified
✅ Customer Analytics: 50 customers processed
✅ Top Customers: Real customer rankings
✅ Coupon Performance: Live usage statistics
✅ Order Management: 50 orders, 35 completed
✅ N8N Integration: Schema compatibility verified
✅ Zero demo data: 100% real WooCommerce integration

🤝 Support & Maintenance

Status: ✅ Production Ready
Platform: EasyPanel optimized
N8N Compatible: Schema validation layer included
Tech Stack: TypeScript + Node.js + Express + Docker
Last Updated: 2025-08-31
Verified: Real WooCommerce data integration + N8N compatibility

Ready for production deployment with complete WooCommerce e-commerce automation capabilities and N8N workflow integration.

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables AI assistants to interact with WooCommerce stores through 37 specialized tools for managing products, orders, customers, categories, and coupons. Includes n8n webhook integration for automated e-commerce workflows and is optimized for Docker deployment on EasyPanel.

Related MCP Servers

WordPress MCP Server
LiamCioci
-
security
A
license
-
quality
Enables AI assistants to interact with WordPress sites through the REST API. Supports multiple WordPress sites with secure authentication, enabling content management, post operations, and site configuration through natural language.
Last updated -
25
MIT License
Terminal.shop MCP Server
pashaydev
A
security
A
license
A
quality
Allows AI assistants to seamlessly interact with Terminal.shop to browse products, manage shopping carts, place orders, and handle subscriptions through Terminal.shop's API.
Last updated -
19
29
1
MIT License
WordPress MCP Server
prathammanocha
A
security
A
license
A
quality
Enables AI assistants to interact with WordPress sites through REST APIs, allowing programmatic management of posts, users, comments, categories, and tags with secure authentication.
Last updated -
29
44
MIT License
MCP Dynamics 365 Commerce Server
jiantmo
-
security
F
license
-
quality
Enables AI assistants to interact with Dynamics 365 Commerce systems through 125+ tools covering customer management, sales orders, cart operations, product searches, inventory tracking, and store operations. Provides comprehensive mock data for development and testing purposes.
Last updated -

View all related MCP servers