WooCommerce Connector

A read-only connector for merchant order, customer, and inventory workflows. It exposes REST endpoints and MCP tools backed by a WooCommerce REST API key, without requiring a model-provider key.

Scope

• Read and search orders, order notes, customers, and products; summarize low stock and sales.

• Authenticate with a dedicated WooCommerce consumer key/secret. External stores must use HTTPS.

• Expose tools through an MCP stdio server and a machine-readable specification at mcp_spec/tool_spec.json.

• Handle upstream throttling and transient failures with a Redis-backed token bucket, bounded retries, and a circuit breaker.

The connector performs reads only. It does not create or modify products, orders, payments, or customers. See capabilities and limits and the merchant workflow.

Related MCP server: ai.studio/woocommerce-gold

Configure

Create a WooCommerce REST API key for a dedicated user with Read permission. Keep the consumer key and secret private.

if (-not (Test-Path .env)) { Copy-Item .env.example .env }

Edit .env and set WOO_BASE_URL, WOO_CONSUMER_KEY, and WOO_CONSUMER_SECRET. Use the store origin (for example, https://shop.example.com), not the REST endpoint path. Do not commit .env or paste credentials into issues or logs.

Run

Start Redis, install the dependencies, and run the connector on the host. Running the connector on the host also allows WooCommerce Local domains and locally trusted CA certificates to work without container-specific network configuration.

docker compose up -d redis
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m uvicorn src.app:app --host 127.0.0.1 --port 8000

Open http://localhost:8000/docs for the REST API. Health endpoints are /health, /health/woocommerce, and /health/redis.

Interfaces

• GET /api/orders, /api/orders/{id}, and /api/orders/{id}/notes

• GET /api/products and /api/products/{id}

• GET /api/customers, /api/customers/{id}, and /api/customers/{id}/orders

• GET /api/tools/ lists the allowlisted operations; POST /api/tools/{name}/execute runs one.

• MCP stdio exposes the same ten read tools. The canonical input schemas are in mcp_spec/tool_spec.json.

For a read-only smoke check, use an existing product ID from your store:

Invoke-RestMethod 'http://localhost:8000/api/products?per_page=5'
Invoke-RestMethod 'http://localhost:8000/api/products/PRODUCT_ID'

To run the MCP server, stop the REST process and start it from the same repository and environment:

.\.venv\Scripts\python.exe -m src.mcp.server

Configure an MCP-compatible client to launch .venv\Scripts\python.exe with arguments -m src.mcp.server and this repository as its working directory. The MCP server uses stdio; do not write logs to stdout.

Test

Tests use isolated in-process transports and do not need store credentials or customer data.

py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\ruff.exe check src tests

Operational Boundaries

The API is intended for local evaluation and has no caller authentication or tenant isolation. Keep it bound to loopback; do not expose it publicly without adding an authentication and authorization layer. Responses may contain merchant customer data, so restrict access and logs. Redis caching can return stale results. Low-stock and sales summaries inspect at most 100 records; neither is a replenishment recommendation or a complete large-catalog report. No merchant pilot or business impact is claimed.

See architecture for request flow. The repository is MIT licensed; see LICENSE.