mcp-server-woocommerce

# MCP Server for WooCommerce

> A Model Context Protocol (MCP) server that enables AI assistants to manage WooCommerce stores through 101 tools, 7 resources, and 5 guided prompts.

This TypeScript server wraps the WooCommerce REST API into MCP-compatible tools for products, orders, refunds, order notes, customers, coupons, reviews, payment gateways, shipping, taxes, webhooks, settings, system status, data, reports, and media management. Every tool supports field filtering to minimize token usage. All tools are annotated with behavior hints (readOnlyHint, destructiveHint, idempotentHint) for safe autonomous operation.

## Setup

- [README](https://github.com/AmitGurbani/mcp-server-woocommerce#readme): Installation, configuration, and usage guide
- [Contributing](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/CONTRIBUTING.md): Development setup and contribution guidelines

## Tools (101)

- [Products](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/src/tools/products.ts): List, get, create, update, delete products with support for attributes, default_attributes, and brands
- [Categories](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/src/tools/categories.ts): List, get, create, update, delete product categories (hierarchical)
- [Tags](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/src/tools/tags.ts): List, get, create, update, delete product tags (flat labels)
- [Brands](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/src/tools/brands.ts): List, get, create, update, delete product brands (WooCommerce 9.6+)
- [Attributes](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/src/tools/attributes.ts): Global attributes and attribute terms with batch support
- [Variations](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/src/tools/variations.ts): Product variations CRUD and batch operations for variable products
- [Orders](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/src/tools/orders.ts): List, get, create, update, delete orders with full line item and status management
- [Order Refunds](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/src/tools/refunds.ts): List, create, and delete order refunds
- [Order Notes](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/src/tools/order-notes.ts): List, create, and delete order notes
- [Customers](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/src/tools/customers.ts): List, get, create, update customer profiles
- [Coupons](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/src/tools/coupons.ts): List, get, create, update, delete discount coupons
- [Product Reviews](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/src/tools/reviews.ts): List, get, update, and delete product reviews
- [Shipping](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/src/tools/shipping.ts): Shipping zones, zone methods, and shipping classes
- [Taxes](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/src/tools/taxes.ts): Tax rates and tax classes management
- [Webhooks](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/src/tools/webhooks.ts): Create, manage, and monitor webhook subscriptions
- [Payment Gateways](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/src/tools/payment-gateways.ts): List, get, and update payment gateway settings
- [Settings](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/src/tools/settings.ts): Read and update WooCommerce store configuration
- [System Status](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/src/tools/system-status.ts): Get system status, list and run system tools
- [Data](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/src/tools/data.ts): List countries and currencies
- [Reports](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/src/tools/reports.ts): Sales reports, top sellers, order/product/customer totals
- [Media](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/src/tools/media.ts): List, delete, and cleanup orphaned media via WordPress REST API

## Resources (7)

- Product Schema (`woo://schema/product`): Product fields, types, statuses, and key rules
- Order Schema (`woo://schema/order`): Order fields, status lifecycle, and payment info
- Coupon Schema (`woo://schema/coupon`): Coupon types, limits, restrictions, and rules
- Refund Schema (`woo://schema/refund`): Refund fields, reasons, line items, and processing rules
- Product Types Reference (`woo://reference/product-types`): When to use simple, variable, grouped, or external products
- Order Statuses Reference (`woo://reference/order-statuses`): Order status transitions and lifecycle diagram
- Payment Gateways Reference (`woo://reference/payment-gateways`): Available payment gateways and configuration options

## Prompts (5)

- `setup_variable_product`: End-to-end variable product creation (attribute, terms, product, variations, publish)
- `process_order`: Review an order and recommend the appropriate status transition
- `catalog_overview`: Parallel 5-tool dashboard of products, orders, customers, categories, and top sellers
- `handle_refund`: Guided refund processing — review order, select items, create refund, verify
- `moderate_reviews`: Review pending product reviews and recommend approve/update/delete actions

## Transport Modes

The server supports two transport modes:

- **stdio** (default): For local AI tools (Claude Code, Claude Desktop, Cursor). Runs via `npx` with no extra config.
- **HTTP** (`MCP_TRANSPORT=http`): For remote access from Claude mobile, ChatGPT, or web clients. Supports two auth modes: bearer token (`MCP_AUTH_TOKEN`) or OAuth 2.1 via Auth0 (`AUTH0_DOMAIN` + `AUTH0_AUDIENCE`). Listens on port 3000 (configurable via `MCP_PORT`). Health check available at `GET /health` (no auth required).

HTTP mode uses the MCP SDK's StreamableHTTPServerTransport with per-session server instances and SSE streaming. OAuth 2.1 enables Claude.ai web/mobile Connectors with automatic `/.well-known/oauth-protected-resource` discovery.

## Configuration

Requires WooCommerce REST API credentials (Consumer Key + Secret) with Read/Write permissions.

Environment variables:
- `WORDPRESS_SITE_URL` (required): WordPress store URL
- `WOOCOMMERCE_CONSUMER_KEY` (required): REST API consumer key (`ck_...`)
- `WOOCOMMERCE_CONSUMER_SECRET` (required): REST API consumer secret (`cs_...`)
- `WORDPRESS_USERNAME` (optional): WordPress admin username for media tools
- `WORDPRESS_APP_PASSWORD` (optional): WordPress Application Password for media tools
- `MCP_TRANSPORT` (optional): Set to `http` for remote access (default: `stdio`)
- `PORT` (optional): Platform-provided port (Hostinger, Railway); overrides `MCP_PORT`
- `MCP_PORT` (optional): HTTP server port (default: `3000`)
- `MCP_AUTH_TOKEN` (optional): Bearer token for HTTP auth (alternative to OAuth 2.1)
- `AUTH0_DOMAIN` (optional): Auth0 tenant URL for OAuth 2.1 (e.g. `https://your-tenant.us.auth0.com`)
- `AUTH0_AUDIENCE` (optional): Auth0 API identifier for OAuth 2.1 token validation
- `MCP_SERVER_URL` (optional): Public server URL for OAuth 2.1 resource metadata discovery

Either `MCP_AUTH_TOKEN` or `AUTH0_DOMAIN` + `AUTH0_AUDIENCE` + `MCP_SERVER_URL` is required when `MCP_TRANSPORT=http`.

## Optional

- [Architecture](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/CLAUDE.md): Codebase architecture, patterns, and adding new tools
- [Deployment Guide](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/docs/DEPLOYMENT.md): Deploy to Railway, Fly.io, or Docker with Auth0 OAuth 2.1
- [Registry Guide](https://github.com/AmitGurbani/mcp-server-woocommerce/blob/main/docs/REGISTRY.md): Publishing to MCP registries (Smithery, Glama, mcp.so)