Quadica/woocommerce-mcp-server

WooCommerce MCP Server On The Luxeon Site

Details about the deployment of a Model Context Protocol (MCP) server on the luxeonstar.com website.

Overview

This MCP server enables interaction with our WooCommerce stores through the WordPress REST API. It provides comprehensive tools for managing all aspects of products, orders, customers, shipping, taxes, discounts, and store configuration using JSON-RPC 2.0 protocol.

A MCP server created using this repo is currently deployed as the luxeon-mcp service on our elestio account our elestio account

The deployment of this repo on elestio was long and complex, but was ultimately successful. See the ai-setup-chat.md document in the docs folder for a complete transcript of the process. Only the very last part is relevant. The first 90% wa just the process of debugging the deployment on elestio.

Deployment on Elestio

This application is a command-line tool and not a standard web server. To deploy it as a web-accessible API in our Elestio account, it must be wrapped in a web server (like Express), and the platform's Docker environment must be configured correctly.

The deployment process requires the following key configurations:

1. Web Server Wrapper

A server.js file has been added to the root of the project. This file creates an Express.js server that listens for HTTP requests and executes the core application (build/index.js) as a child process, piping data back and forth.

2. Environment Variables

The application requires the following environment variables to be set in the Elestio "ENV" tab for the luxeonstar.com site:

DOMAIN=luxeon-mcp-u44324.vm.elestio.app
WORDPRESS_SITE_URL=https://stg-luxeonstarleds-lxplugin.kinsta.cloud/
WOOCOMMERCE_CONSUMER_KEY=ck_xxxxxx
WOOCOMMERCE_CONSUMER_SECRET=cs_xxxxxx
WORDPRESS_USERNAME=ronw
WORDPRESS_PASSWORD=xxxxx
MCP_SERVER_API_KEY=xxxxx

The currently used keys will be visible in the elestio ENV tab.

3. Docker Compose Configuration

The Elestio "Docker Compose" configuration for the app service must be modified to correctly run the application. The final app service definition should look like this:

app:
   build:
    context: ./nodejs
    dockerfile: Dockerfile
    args:
      - SOFTWARE_VERSION_TAG=${SOFTWARE_VERSION_TAG}
   restart: unless-stopped
   container_name: app-nodejs
   ports:
    - '172.17.0.1:3000:3000'
   volumes:
     - /usr/src/app:/usr/src/app
   working_dir: /usr/src/app
   env_file:
     - .env
   command: npm start
   depends_on:
    - redis

API Methods

The server supports both WordPress and WooCommerce API methods. Here's a list of available methods grouped by category:

WordPress Content Management

These methods require WordPress username/password credentials and are independent of the WooCommerce API.

WooCommerce Products

Product Categories

Product Tags

Product Attributes

Product Variations

Product Reviews

WooCommerce Orders

Order Notes

Order Refunds

WooCommerce Customers

Shipping

Taxes

Discounts/Coupons

Payment Gateways

Reports

Settings

System Status

Data

Method Parameters

All methods follow a similar parameter structure. Here are some examples:

Common Parameters for All Methods

• siteUrl: (optional if set in env) WordPress site URL

Additional Parameters for WooCommerce Methods

• consumerKey: (optional if set in env) WooCommerce consumer key
• consumerSecret: (optional if set in env) WooCommerce consumer secret

Additional Parameters for WordPress Methods

• username: (optional if set in env) WordPress username
• password: (optional if set in env) WordPress password

Example Usage

WordPress API Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "create_post",
  "params": {
    "siteUrl": "https://your-wordpress-site.com",
    "username": "your-wordpress-username",
    "password": "your-wordpress-password",
    "title": "My New Blog Post",
    "content": "This is the content of my new blog post.",
    "status": "publish"
  }
}

WooCommerce Products Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_products",
  "params": {
    "perPage": 20,
    "page": 1,
    "filters": {
      "category": 19,
      "status": "publish"
    }
  }
}

Create Product Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "create_product",
  "params": {
    "productData": {
      "name": "Premium T-Shirt",
      "type": "simple",
      "regular_price": "29.99",
      "description": "Comfortable cotton t-shirt, available in various sizes.",
      "short_description": "Premium quality t-shirt.",
      "categories": [
        {
          "id": 19
        }
      ],
      "images": [
        {
          "src": "http://example.com/wp-content/uploads/2022/06/t-shirt.jpg"
        }
      ]
    }
  }
}

Product Metadata Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "create_product_meta",
  "params": {
    "productId": 456,
    "metaKey": "_custom_product_field",
    "metaValue": {
      "special_attribute": "value",
      "another_attribute": 42
    }
  }
}

Order Metadata Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "create_order_meta",
  "params": {
    "orderId": 789,
    "metaKey": "_delivery_instructions",
    "metaValue": "Leave package at the back door"
  }
}

Security Note

For WooCommerce REST API access, you need to generate API keys. You can create them in your WordPress dashboard under WooCommerce → Settings → Advanced → REST API.

Requirements

This project has different requirements depending on whether you are running the pre-compiled code or modifying the source code.

To Run the Deployed Application

• Node.js 20.0.0 or higher: The execution environment for the server.
• NPM (Node Package Manager): Required to install dependencies.
• Express.js: This project uses the Express framework to function as a web server. It is listed as a dependency and will be installed automatically with npm install.

External Services

• A publicly accessible WordPress site with the WooCommerce plugin installed and active.
• WooCommerce REST API keys (Consumer Key and Consumer Secret) with Read/Write permissions.
• A WordPress user account (username and application password) with sufficient permissions to interact with WooCommerce.

To Modify the Source Code (Development)

• All of the above.
• TypeScript: The project's source code is written in TypeScript (/src directory). The devDependencies include the necessary TypeScript packages.
• Build Step: Before the application can be run, the TypeScript source code must be compiled into JavaScript. This is done by running the build script defined in package.json:

# This command compiles the code from /src into JavaScript in the /build directory.
npm run build

License

MIT License - See LICENSE file for details