Skip to main content

Installation

Prerequisites, building from source, and running the WooCommerce MCP Server in stdio or HTTP mode.

Prerequisites​

Before installing the WooCommerce MCP Server, ensure you have the following:

RequirementDetails
Node.jsVersion 20.0 or higher (download)
npmIncluded with Node.js
WordPress SiteRunning WordPress 5.0+ with WooCommerce 7.0+
WooCommerce REST API KeysConsumer Key and Consumer Secret with Read/Write permissions
GitFor cloning the repository

Generating WooCommerce API Keys​

The WOOCOMMERCE_CONSUMER_KEY and WOOCOMMERCE_CONSUMER_SECRET are generated from within the WooCommerce admin panel. These credentials authenticate the MCP server against the WooCommerce REST API.

  1. Log into your WordPress admin dashboard
  2. Navigate to WooCommerce → Settings → Advanced → REST API
  3. Click Add key
  4. Set the User to developer (our standard service account for API integrations)
  5. Set the Description (e.g., "MCP Server — VS Code" or "MCP Server — PhpStorm")
  6. Set Permissions to Read/Write
  7. Click Generate API key
  8. Immediately copy both values — they are only displayed once:
    • Consumer Key — starts with ck_ (this is your WOOCOMMERCE_CONSUMER_KEY)
    • Consumer Secret — starts with cs_ (this is your WOOCOMMERCE_CONSUMER_SECRET)
caution

The Consumer Secret is only shown once at generation time. If you lose it, you must revoke the key and generate a new one.

Important notes:

  • Always generate keys under the developer user account — never use a personal admin account
  • Each developer or integration should have its own key pair for auditability
  • Keys can be revoked at any time from the same REST API settings page without affecting other integrations

Generating a WordPress Application Password (Optional)​

Required only if you plan to use WordPress content tools (create_post, get_posts, update_post, post metadata operations):

  1. Navigate to Users → Edit the developer user account
  2. Scroll to the Application Passwords section
  3. Enter a name (e.g., "MCP Server") and click Add New Application Password
  4. Copy the generated password immediately — it is shown only once
  5. The WORDPRESS_USERNAME is always developer

Installation Steps​

1. Clone the Repository​

git clone https://github.com/Rhino-Group/woocommerce-mcp-server.git
cd woocommerce-mcp-server

2. Install Dependencies​

npm install

3. Build the TypeScript Source​

npm run build

This compiles TypeScript from src/ into JavaScript in the build/ directory.

4. Verify the Build​

node build/index.js --help

If no errors appear, the build is successful. The server will wait for MCP protocol messages on stdin.

Environment Variables​

The server is configured entirely through environment variables. These can be set in your shell, in your IDE's MCP configuration, or in a .env file for HTTP mode.

VariableRequiredDescription
WORDPRESS_SITE_URLYesFull URL of your WordPress site (e.g., https://your-site.com)
WOOCOMMERCE_CONSUMER_KEYYesWooCommerce REST API consumer key (ck_xxx)
WOOCOMMERCE_CONSUMER_SECRETYesWooCommerce REST API consumer secret (cs_xxx)
WORDPRESS_USERNAMENoWordPress username for post/meta operations
WORDPRESS_PASSWORDNoWordPress Application Password for post/meta operations
MCP_API_KEYNoAPI key for authenticating HTTP admin endpoint requests
ALLOW_SELF_SIGNED_CERTSNoSet to true for local development with self-signed SSL certificates
PORTNoHTTP server port (default: 3000)

Running the Server​

In stdio mode, the MCP client (VS Code or PhpStorm) spawns the server as a child process and communicates via stdin/stdout. You do not run this manually — your IDE handles it automatically based on your MCP configuration.

To test manually:

WORDPRESS_SITE_URL="https://your-site.com" \
WOOCOMMERCE_CONSUMER_KEY="ck_xxx" \
WOOCOMMERCE_CONSUMER_SECRET="cs_xxx" \
node build/index.js

The server will start and wait for JSON-RPC messages on stdin.

HTTP Mode (Remote Access)​

For remote access or Docker deployments, the HTTP transport exposes REST endpoints:

WORDPRESS_SITE_URL="https://your-site.com" \
WOOCOMMERCE_CONSUMER_KEY="ck_xxx" \
WOOCOMMERCE_CONSUMER_SECRET="cs_xxx" \
MCP_API_KEY="your-secret-key" \
node build/http.js

The server starts on port 3000 (or the port specified by PORT) with three endpoints:

EndpointMethodAuthDescription
/healthGETNoneHealth check ({"status": "ok", "timestamp": "..."})
/mcpPOSTNonePublic endpoint — 4 sanitized read-only product tools
/mcp/adminPOSTBearer tokenAdmin endpoint — all 159+ tools with full data access

Testing the HTTP Server​

# Health check
curl http://localhost:3000/health

# List available public tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# List admin tools (requires API key)
curl -X POST http://localhost:3000/mcp/admin \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-key" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Self-Signed Certificate Support​

For local development environments using tools like Laravel Herd, Valet, Local by Flywheel, or MAMP that generate self-signed SSL certificates:

ALLOW_SELF_SIGNED_CERTS=true

This disables Node.js TLS certificate verification for outbound requests to your WordPress site. Never enable this in production.

Troubleshooting​

Build Fails​

  • Ensure Node.js 20+ is installed: node --version
  • Delete node_modules and reinstall: rm -rf node_modules && npm install
  • Clear the build directory: rm -rf build && npm run build

Connection Refused​

  • Verify WORDPRESS_SITE_URL is correct and accessible from your machine
  • Check that WooCommerce REST API is enabled (WooCommerce → Settings → Advanced → REST API)
  • For HTTPS sites with self-signed certs, set ALLOW_SELF_SIGNED_CERTS=true

Authentication Errors​

  • Verify your Consumer Key and Secret are correct (regenerate if needed)
  • Ensure API keys have Read/Write permissions
  • For WordPress post operations, verify the Application Password is active

Next Steps​