MCP WooCommerce Server - Real Protocol Implementation
🚀 Project Overview
Complete MCP (Model Context Protocol) server for WooCommerce integration with native protocol support
- Name: mcp-woocommerce-server
- Goal: True MCP protocol implementation for WooCommerce automation with n8n
- Features: 44+ WooCommerce tools via native MCP protocol with Mexican market support (MXN currency), customer analytics, order email lookup, and real API integration
🎯 URLs & Endpoints
Production URLs
- GitHub: https://github.com/Marckello/mcp_woo_marckello
- Demo Server: https://3000-i0pmg1zszswkdqf58h7ot-6532622b.e2b.dev
MCP Protocol Endpoints
- WebSocket MCP:
ws://hostname:3000/mcp-ws (for n8n MCP node) - Server-Sent Events:
GET /mcp-sse (HTTP streaming) - HTTP JSON-RPC:
POST /mcp (fallback endpoint) - Health Check:
GET /health - Store Info:
GET /info - N8n Webhook:
POST /webhook/n8n
🏗️ MCP Protocol Architecture
Native MCP Implementation
- MCPTransport (
src/transport/mcp-transport.ts): WebSocket & SSE transport layers - MCPProtocolHandler (
src/protocol/mcp-handler.ts): JSON-RPC 2.0 message handling - Session Management: UUID-based session tracking with capabilities
- Bidirectional Communication: Real-time MCP protocol compliance
MCP Protocol Features
- Protocol Version: MCP 2024-11-05
- JSON-RPC 2.0: Full compliance with MCP specification
- Multiple Transports: WebSocket, SSE, HTTP support
- Tool Discovery: Dynamic tool listing and execution
- Resource Management: Store info and settings via MCP resources
- Smart Date Detection: Intelligent date parsing with timezone context
- Mexico Timezone: Native UTC-6 (America/Mexico_City) support
🔧 Data Architecture
WooCommerce Integration
- 44+ MCP Tools: Complete WooCommerce API coverage with customer analytics & order email lookup
- Product Tools: Create, read, update, delete, batch operations
- Order Tools: Order management, notes, status updates, email-based order lookup
- Customer Tools: Customer CRUD operations, top customers analysis, purchase history
- Analytics Tools: 12 comprehensive sales analytics with smart date detection
- Promotion Tools: Active promotions, discounts, and special offers management
- Mexican Market: Native MXN (Pesos Mexicanos) currency support
- Real API Integration: Direct connection to live WooCommerce stores
- Authentication: OAuth 1.0a with consumer key/secret
- Timezone Aware: All date queries use Mexico City timezone (UTC-6)
Storage & Services
- WooCommerce REST API: v1, v2, v3 support
- Session Storage: In-memory session management
- Logging: Winston-based structured logging
- Validation: Joi schema validation for all inputs
👨💻 User Guide
For n8n Users
- Add MCP Node: Use n8n's MCP integration node
- WebSocket URL:
ws://your-server:3000/mcp-ws - Protocol: Select "MCP 2024-11-05"
- Tools Available: 44+ WooCommerce automation tools including customer analytics and order email lookup
- Authentication: Configure WooCommerce credentials in server .env
Smart Date Detection Features
- Natural Language: Use "28 de agosto" or "August 28" for date queries
- Context Aware: Automatically detects if date is past/future based on current time
- n8n Integration: Use
{{ $now }} variable for current date context - Mexico Timezone: All calculations in UTC-6 (America/Mexico_City)
Example Analytics Queries:
// Get sales for August 28 (automatically detects correct year)
{
"name": "wc_get_daily_sales",
"arguments": {
"period": "28 de agosto",
"context_date": "{{ $now }}" // n8n current datetime
}
}
// Get top customers by total spending
{
"name": "wc_get_top_customers",
"arguments": {
"metric": "total_spent",
"limit": 5
}
}
// Get active promotions and discounts
{
"name": "wc_get_promotions_active",
"arguments": {
"status": "active",
"type": "coupon"
}
}
// Get customer purchase history
{
"name": "wc_get_customer_purchase_history",
"arguments": {
"customer_id": 45,
"include_products": true
}
}
// Find orders by email address (NEW!)
{
"name": "wc_get_orders_by_email",
"arguments": {
"email": "customer@example.com",
"status": "completed"
}
}
For Direct API Usage
// Initialize MCP connection
POST /mcp
{
"jsonrpc": "2.0",
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"clientInfo": {"name": "my-client", "version": "1.0.0"},
"capabilities": {"tools": {}}
},
"id": 1
}
// List available tools
POST /mcp
{
"jsonrpc": "2.0",
"method": "tools/list",
"id": 2
}
// Execute WooCommerce tool
POST /mcp
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "wc_get_products",
"arguments": {"per_page": 10}
},
"id": 3
}
🚀 Deployment
Current Status
- Platform: E2B Sandbox (Development)
- Status: ✅ Active - MCP Protocol Real Implementation Complete
- Tech Stack: Node.js + TypeScript + Hono + WebSocket + MCP SDK
- Process Manager: PM2 with ecosystem.config.cjs
EasyPanel Deployment
- Repository: Use GitHub repo
mcp_woo_marckello - Docker: Multi-stage build with production optimization
- Environment: Copy
.env.easypanel template - Port: 3000 (HTTP + WebSocket)
- Health:
/health endpoint for monitoring
Local Development
# Install dependencies
npm install
# Build TypeScript
npm run build
# Start with PM2
pm2 start ecosystem.config.cjs
# Test MCP protocol
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "method": "initialize", "id": 1}'
🏪 WooCommerce API Setup
Required API Permissions
For real WooCommerce integration, ensure your API key has proper permissions:
- WordPress Admin → WooCommerce → Settings → Advanced → REST API
- Create API Key or Edit existing key
- Permissions: Set to "Read/Write" or minimum "Read" for analytics
- User: Select admin user with WooCommerce access
- Generate/Update and copy credentials to
.env file
Currency Configuration
- Default Currency: Mexican Pesos (MXN)
- Market Focus: Mexican e-commerce market
- Realistic Values: All demo data scaled for Mexican market
- Real Integration: Connects to live WooCommerce for accurate MXN data
🎯 Implementation Status
✅ Completed Features
- Native MCP Protocol: Complete JSON-RPC 2.0 implementation
- Multiple Transports: WebSocket, SSE, HTTP support
- 44+ WooCommerce Tools: Full API coverage via MCP with customer analytics & order email lookup
- Smart Analytics: 12 analytics tools with intelligent date detection
- Mexican Market Support: MXN currency, realistic pricing, Mexico timezone
- Real API Integration: Direct connection to live WooCommerce stores
- Mexico Timezone: Native UTC-6 support with n8n {{ $now }} integration
- Session Management: UUID-based session tracking
- Production Ready: PM2, logging, error handling
- GitHub Integration: Source control with deployment ready
- Docker Support: Multi-stage production builds
📋 Ready for Next Steps
- EasyPanel Deployment: Repository ready for container deployment
- N8n Integration: Native MCP WebSocket connection support
- Real Credentials: Update .env with actual WooCommerce API keys
- Production Scaling: PM2 cluster mode and load balancing
🔄 Integration Flow
n8n MCP Node → WebSocket → MCP Transport → Protocol Handler → WooCommerce Tools → API Response → MCP Response → n8n
Last Updated: August 30, 2025 - v1.3.3 Production-Safe Data Handling Complete
🔒 Production vs Development Mode
✅ Production Mode (Real WooCommerce Data)
When you deploy with real WooCommerce credentials:
- Data Source:
"source": "woocommerce_api" - Real Data: Actual coupons, orders, customers from your store
- Live Statistics: Real usage counts, revenue, conversion rates
- No Warnings: Clean responses with actual business data
⚠️ Demo Mode (Development Data)
When credentials are missing or contain demo/test:
- Data Source:
"source": "demo_data" - Demo Data: Mexican market sample data for development
- Clear Warnings:
"data_warning": "⚠️ DEMO DATA - Replace with real WooCommerce credentials" - Testing Safe: Perfect for development and n8n workflow testing
🔄 Automatic Detection
The system automatically detects mode based on your .env configuration:
# Production Mode (uses real API)
WOOCOMMERCE_SITE_URL=https://your-real-store.com
WOOCOMMERCE_CONSUMER_KEY=ck_real_key_here
WOOCOMMERCE_CONSUMER_SECRET=cs_real_secret_here
# Demo Mode (uses demo data)
WOOCOMMERCE_SITE_URL=https://demo.woothemes.com
WOOCOMMERCE_CONSUMER_KEY=ck_demo_key_for_testing
WOOCOMMERCE_CONSUMER_SECRET=cs_demo_secret_for_testing
🆕 v1.3.3 Latest Features
- 🔒 Production-Safe Data Handling: Intelligent detection between real WooCommerce API and demo mode
- Order Email Lookup:
wc_get_orders_by_email - Find orders by customer email address for support queries - Real API Integration: Uses actual WooCommerce data when valid credentials are configured
- Demo Mode Warnings: Clear
⚠️ DEMO DATA warnings when using development data - Coupon Analytics: Complete coupon usage statistics with real store data or demo fallback
- Customer Analytics:
wc_get_top_customers - Real customer data from your WooCommerce store - Enhanced Routing: Smart tool routing for orders, customers, analytics, and coupons
- Mexican Market Support: Realistic demo data for development and testing
- Schema Optimization: All schemas optimized for n8n compatibility (no default values)