WooCommerce MCP Toolkit

MCP toolkit for securely querying, diagnosing and managing WooCommerce stores through the WordPress Abilities API. The plugin uses WooCommerce CRUD/query APIs, declares HPOS compatibility, returns compact structured data, and keeps all mutations disabled by default.

Requirements

• PHP 8.1+
• WordPress 6.9+ (the server-side Abilities API is in core)
• A current stable WooCommerce release
• Optional: wordpress/mcp-adapter to expose abilities through MCP

The plugin does not bundle or implement an MCP server. Install the official Adapter as a plugin or Composer package. Its default server discovers abilities carrying meta.mcp.public at /wp-json/mcp/mcp-adapter-default-server or through wp mcp-adapter serve.

Architecture

MCP Adapter → WordPress Abilities API → thin ability callback → service → WooCommerce CRUD/API

PermissionManager centralizes authorization. AuditRepository records mutation outcomes in a small indexed table. Services return arrays rather than WooCommerce objects and deliberately omit customer addresses, emails, secrets, gateway settings, and Action Scheduler arguments.

Abilities

Read-only: store-summary, get-order, search-orders, order-stats, get-product, search-products, low-stock-products, out-of-stock-products, sales-summary, top-products, system-status, hpos-status, payment-gateways, failed-scheduled-actions, template-overrides, and store-diagnose.

Opt-in writes: add-order-note, update-order-status, update-product-stock, and update-product-price. Enable each under WooCommerce → MCP Toolkit. Enabling an operation never bypasses the manage_woocommerce check.

Analytics definitions and limits

Sales summary includes processing and completed orders. “Gross sales” means order totals before refunds; “net sales” means those totals less refunds. Both include taxes and shipping. Phase-one analytics intentionally use stable order CRUD APIs and cap scans at 500 orders; responses disclose truncation. A future adapter behind AnalyticsService can use a stable analytics datastore without changing ability contracts.

List endpoints cap per_page/limit at 100. Low-stock evaluation respects wc_get_low_stock_amount() per product and limits the candidate scan.

MCP client example

{
  "mcpServers": {
    "woocommerce": {
      "command": "wp",
      "args": ["--path=/path/to/site", "mcp-adapter", "serve", "--server=mcp-adapter-default-server", "--user=admin"]
    }
  }
}

Use the Adapter's discover-abilities, get-ability-info, and execute-ability tools. Example requests: “Show revenue for the last 30 days”, “Find SKU ABC-123 and check inventory risk”, or “Diagnose this WooCommerce store.”

AI Analyst status

The admin page exposes a placeholder only. The WordPress 7.x Connectors/provider APIs are still evolving, so this release intentionally does not invent a provider contract or store API keys. An eventual integration will consume aggregated service results through a dedicated interface and disclose the exact payload before sending it.

Development

composer install
composer lint
composer test
find . -name '*.php' -not -path './vendor/*' -exec php -l {} \;

Security and privacy

• Authenticated users must have manage_woocommerce.
• Input is constrained by JSON Schema and sanitized again at service boundaries.
• Admin settings use the Settings API, capability checks, nonces, and escaped output.
• Mutations are opt-in and audited with field-level before/after values where practical.
• Order responses omit billing/shipping/customer PII.
• Gateway credentials and scheduled-action arguments are never returned.

Extensibility

Services are ordinary namespaced classes and ability registration is centralized. Consumers can decorate/replace service construction in a future container release without changing public ability IDs. Ability IDs and response shapes should be treated as public API.

License

GPL-2.0-or-later.