✨IntelliCommerce✨ Woo MCP Server

🛒 Transform your WooCommerce store with AI-powered natural language interactions

Features • Quick Start • Documentation • Examples • Contributing

---

Made with 🧡 in Cape Town 🇿🇦
Powered by Xstra AI✨ | Enabled by IntelliCommerce✨

🎯 Overview

The IntelliCommerce✨ Woo MCP server is a commercial-grade Model Context Protocol (MCP) implementation that bridges WooCommerce stores with AI assistants. Talk to your store in natural language through VS Code Copilot, Claude Desktop, or any MCP-compatible client.

🚀 Professional fork of Automattic's WooCommerce MCP server, enhanced with commercial features, comprehensive documentation, and production-ready configuration.

✨ Features

🛒 Complete Store Management Products & Variations - Full catalog control Orders & Fulfillment - Order lifecycle management Customer Data - Comprehensive customer insights Coupons & Discounts - Promotion management Payment Gateways - Payment configuration Shipping & Tax - Logistics and compliance

🤖 AI Integration Natural Language - Talk to your store conversationally Multi-Client Support - VS Code, Claude Desktop, and more Real-time Data - Live WooCommerce API integration Type Safety - Full TypeScript implementation Error Handling - Robust production-grade reliability Security First - Environment-based credential management

🚀 Quick Start

📋 Prerequisites

• Node.js 18+ (tested with v22.15.0)
• WooCommerce Store with REST API enabled
• API Keys with appropriate permissions
• MCP Client (VS Code Copilot, Claude Desktop, etc.)

1️⃣ Global Installation ⭐ Recommended

# Install globally from npm
npm install -g intellicommerce-woo-mcp

# Setup in any project
cd your-project
intellicommerce-woo-mcp setup

# Set environment variables
export WOOCOMMERCE_API_URL="https://your-store.com"
export WOOCOMMERCE_CONSUMER_KEY="ck_your_key"
export WOOCOMMERCE_CONSUMER_SECRET="cs_your_secret"

2️⃣ Local Development Installation

# Clone the repository
git clone https://github.com/jlfguthrie/intellicommerce-woo-mcp.git
cd intellicommerce-woo-mcp

# Install dependencies
npm install

# Build the project
npm run build

3️⃣ Configuration

🔧 Global Installation (Automatic)

After global installation, use the setup command:

# In any project directory
intellicommerce-woo-mcp setup

This creates .vscode/mcp.json:

{
  "mcpServers": {
    "intellicommerce-woo": {
      "command": "intellicommerce-woo-mcp",
      "args": [],
      "env": {}
    }
  }
}

🔧 Local Development (Manual)

For local development, create .env file:

cp .env.example .env

Edit .env with your WooCommerce credentials:

WOOCOMMERCE_API_URL=https://your-store.com
WOOCOMMERCE_CONSUMER_KEY=ck_your_consumer_key
WOOCOMMERCE_CONSUMER_SECRET=cs_your_consumer_secret

3️⃣ Client Setup

🔧 VS Code with Copilot

For Production Use (Global Installation):

{
  "mcpServers": {
    "intellicommerce-woo": {
      "command": "intellicommerce-woo-mcp",
      "args": [],
      "env": {}
    }
  }
}

For Contributing/Customization (Local Build):

{
  "mcpServers": {
    "intellicommerce-woo": {
      "command": "node",
      "args": ["${workspaceFolder}/build/server.js"],
      "env": {}
    }
  }
}

🔐 Security Note: Credentials are loaded from your .env file, not hardcoded in the MCP configuration.

</details>

<details>
<summary><strong>🖥️ Claude Desktop</strong></summary>

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "intellicommerce-woo": {
      "command": "node",
      "args": ["/absolute/path/to/build/server.js"],
      "env": {
        "WOOCOMMERCE_API_URL": "https://your-store.com",
        "WOOCOMMERCE_CONSUMER_KEY": "ck_your_key",
        "WOOCOMMERCE_CONSUMER_SECRET": "cs_your_secret"
      }
    }
  }
}

💡 Note: For Claude Desktop, you need to include credentials in the config file since it doesn't automatically load .env files.

</details>

### 4️⃣ **Launch**

<details>
<summary><strong>🌍 Global Installation (Production Use)</strong></summary>

```bash
# Set environment variables
export WOOCOMMERCE_API_URL="https://your-store.com"
export WOOCOMMERCE_CONSUMER_KEY="ck_your_key"
export WOOCOMMERCE_CONSUMER_SECRET="cs_your_secret"

# Start the server (available globally)
intellicommerce-woo-mcp

💻 Local Development

# Start the server (local development)
npm start

You'll see:

🚀 Initializing ✨IntelliCommerce✨ Woo MCP Server...
✅ WooCommerce client initialized successfully.
🔧 Setting up server transport...
✨ IntelliCommerce✨ Woo MCP Server running on stdio
Made with 🧡 in Cape Town 🇿🇦

💬 Examples

📦 Product Management "List all products with 'shirt' in the name" "What's the price of product ID 123?" "Create a new product called 'Summer Hat'" "Update product 456 to be on sale" 📋 Order Operations "Show me orders from this week" "Get details for order #1001" "What's the status of recent orders?" "List orders over $100"

👥 Customer Insights "Show customer details for ID 789" "List customers from Cape Town" "Find customers with no orders" "Get top spending customers" 🎫 Promotions "List all active coupons" "Create a 15% discount code" "Show coupon usage statistics" "Disable expired promotions"

📚 Documentation

📖 Guide	🎯 Purpose	🔗 Link
Setup	Installation & Configuration	📋 Setup Guide
API Reference	Complete Tool Documentation	🛠️ API Docs
Troubleshooting	Common Issues & Solutions	🔧 Troubleshooting
Changelog	Version History	📈 Changelog

🛠️ Available Tools

📦 Products (6 tools)

• list_products - List all products with search and pagination
• get_product - Get specific product details
• create_product - Create new products
• update_product - Update existing products
• delete_product - Remove products
• list_product_variations - Manage product variations

📋 Orders (5 tools)

• list_orders - List orders with filtering
• get_order - Get order details
• create_order - Create new orders
• update_order - Update order status
• delete_order - Remove orders

👥 Customers (5 tools)

• list_customers - List all customers
• get_customer - Get customer details
• create_customer - Add new customers
• update_customer - Update customer data
• delete_customer - Remove customers

🎫 Coupons, 💳 Payments, 🚚 Shipping, 💰 Refunds, 💸 Tax Rates

45+ total tools covering all major WooCommerce entities with full CRUD operations.

🔐 Security

• ✅ Environment Variables - Never commit credentials
• ✅ API Key Permissions - Least privilege access
• ✅ Input Validation - Prevent injection attacks
• ✅ HTTPS Enforcement - Secure API communications
• ✅ Rate Limiting - Prevent API abuse

🌟 Why Choose IntelliCommerce✨ Woo MCP?

Commercial Grade Production-ready with comprehensive error handling

Type Safe Full TypeScript implementation with type safety

Well Documented Comprehensive guides and troubleshooting

Global Installation One-command setup across all projects

Cape Town Built Local South African development with pride

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m '✨ feat: Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

📋 Development Setup

# Install dependencies
npm install

# Start development with watch mode
npm run dev

# Type checking
npm run typecheck

# Format code
npm run format

📊 Project Stats

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Attribution

This project is a commercial fork and enhancement of the WooCommerce MCP server originally created by Automattic Inc. as part of their ai-experiments repository.

We gratefully acknowledge the original authors and contributors.

---

🏷️ About IntelliCommerce✨

IntelliCommerce✨ is a Cape Town-based technology company specializing in AI-powered e-commerce solutions. We create innovative tools and integrations that bridge the gap between artificial intelligence and online commerce platforms.

🌐 Website • 📧 Email • 👨‍💻 Developer

Made with 🧡 in Cape Town 🇿🇦
Powered by Xstra AI✨ | Enabled by IntelliCommerce✨

🛠️ Development

📋 Development Commands

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

# Development with watch mode
npm run dev

# Clean build directory
npm run clean

# Type checking
npm run typecheck

# Format code
npm run format

# Local sanity check
npm run sanity:check

# Local manual release
npm run local:release

🧪 Local Testing

# Test MCP connection with inspector
npm run test:mcp

# Local sanity check
npm run sanity:check

🔧 Advanced Configuration

⚙️ Environment Variables

# Required
WOOCOMMERCE_API_URL=https://your-store.com
WOOCOMMERCE_CONSUMER_KEY=ck_your_key
WOOCOMMERCE_CONSUMER_SECRET=cs_your_secret

# Optional
NODE_ENV=development
DEBUG=true
API_TIMEOUT=30000
LOG_LEVEL=info
LOG_REQUESTS=true
MAX_CONCURRENT_REQUESTS=10
DEFAULT_PAGE_SIZE=20

🔍 Troubleshooting

Common Issues:

1. ❌ "Missing required WooCommerce configuration"

   • Check your .env file exists and has correct values
   • Ensure no extra spaces or quotes in environment variables

2. ❌ "Invalid signature" or 401 Unauthorized

   • Regenerate API keys in WooCommerce admin
   • Verify API key permissions (Read/Write)
   • Check store URL includes https://

3. ❌ Server not showing in VS Code Copilot

   • Verify absolute path to build/server.js in .vscode/mcp.json
   • Restart VS Code after MCP configuration changes

4. ❌ GitHub Tool Schema Errors on Global Install

   • These errors are unrelated to IntelliCommerce✨ Woo MCP
   • Caused by VS Code's JSON schema download being disabled
   • Safe to ignore - they don't affect MCP functionality
   • To fix: Enable json.schemaDownload.enable in VS Code settings

For more troubleshooting, see our Troubleshooting Guide.

Security

• Never commit your API keys or secrets to version control. Use environment variables (the .env file) to store them securely.
• Limit API key permissions: Only grant the necessary permissions (read-only, if possible) to the WooCommerce API keys you use with the IntelliCommerce✨ Woo MCP server.
• Validate Inputs: Thoroughly validate all inputs received from the client (especially tool arguments) to prevent injection attacks or unintended behavior.
• Consider HTTPS: Use HTTPS for communication between the client and server, especially if you're not using the stdio transport. The quickstart enables queryStringAuth and disables certificate checking for local development only. For production, use proper HTTPS certificates.
• Rate Limiting: Implement rate limiting to prevent abuse of your server and the WooCommerce API.

---

Made with 🧡 in Cape Town 🇿🇦 Powered by Xstra AI✨ | Enabled by IntelliCommerce✨