How WooCommerce MCP Turns Your Store Into an AI-Accessible API

What WooCommerce MCP Actually Does

The Model Context Protocol gives AI assistants a structured way to discover and execute operations on external systems. WooCommerce ships a native MCP integration – currently in developer preview starting with version 10.3 – that exposes product listings, order management, and customer data as typed, permission-checked tools. An AI client like Claude Code or Cursor sends a JSON-RPC request, and WooCommerce responds through the same permission model that governs its REST API.

The architecture has three layers. The MCP client communicates over stdio or JSON-RPC to a local proxy called @automattic/mcp-wordpress-remote. That proxy translates protocol messages into HTTP requests aimed at your WordPress site‘s MCP endpoint. On the server side, the WordPress Abilities API receives those requests, checks permissions, and dispatches them to the appropriate WooCommerce controller. This proxy pattern sidesteps the fact that most MCP clients expect stdio transport while WordPress speaks HTTP – the proxy acts as a translator between the two worlds.

Enabling the MCP Feature Flag

WooCommerce gates MCP behind a feature flag, so nothing is exposed until you explicitly opt in.

The quickest path is navigating to WooCommerce > Settings > Advanced > Features in the admin dashboard and checking “Enable MCP Beta.” Programmatic activation works through a filter, which is useful when you need the flag active across staging and production without touching the UI. Drop this into your theme’s functions.php or a site-specific plugin:

add_filter( 'woocommerce_features', function( $features ) {
    $features['mcp_integration'] = true;
    return $features;
} );

After enabling, generate a dedicated REST API key under WooCommerce > Settings > Advanced > REST API. Give it a descriptive label like “MCP Agent – Read Only” and limit permissions to Read unless your workflow genuinely requires write access. The consumer key and secret pair authenticates every MCP request, so treat it like any other API credential – store it outside version control and rotate it on a schedule.

Connecting Claude Code to Your Store

The connection itself takes a single terminal command. Claude Code uses the claude mcp add subcommand to register a new MCP server entry:

claude mcp add woocommerce_mcp 
  --env WP_API_URL=https://yourstore.com/wp-json/woocommerce/mcp 
  --env CUSTOM_HEADERS='{"X-MCP-API-Key": "ck_abc123:cs_def456"}' 
  -- npx -y @automattic/mcp-wordpress-remote@latest

Replace ck_abc123:cs_def456 with the actual consumer key and secret. The npx -y flag ensures the proxy package installs without prompting. Once registered, Claude Code can discover available tools – product CRUD, order queries, customer lookups – and call them during any conversation.

For editors like Cursor or VS Code, add the equivalent JSON block to your MCP settings file:

{
  "mcpServers": {
    "woocommerce_mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote@latest"],
      "env": {
        "WP_API_URL": "https://yourstore.com/wp-json/woocommerce/mcp",
        "CUSTOM_HEADERS": "{"X-MCP-API-Key": "ck_abc123:cs_def456"}"
      }
    }
  }
}

The proxy must run locally – it is not a cloud service. Every AI request routes through your machine, hits the remote WordPress endpoint over HTTPS, and returns the response to the MCP client.

What the Default Abilities Expose

Out of the box, WooCommerce registers abilities that map to existing REST API endpoints for products, orders, and customers. The current implementation uses REST endpoint bridging, meaning each ability is a thin wrapper around a corresponding WooCommerce REST controller. The AI can list products with filters, retrieve a single order by ID, search customers, and update order statuses – all respecting the same permission checks that apply to direct API calls.

Practically, this means an AI agent can answer questions like “show me all orders from the last 7 days with a processing status” or “update product #4521 stock to 0” without you writing any custom code. The HPOS-compatible query layer handles the data retrieval, so stores already migrated to High-Performance Order Storage see no performance regression from MCP-initiated queries.

Registering Custom Abilities for Your Store

The default abilities cover common operations, but real stores have domain-specific logic that no generic tool anticipates. The WordPress Abilities API lets you register custom abilities that the MCP adapter automatically exposes to connected clients.

Here is a practical example – a low-stock alert ability that returns products below a given threshold:

add_action( 'abilities_api_init', function() {
    wp_register_ability( 'your-store/low-stock-check', array(
        'label'       => 'Low Stock Check',
        'description' => 'Returns products with stock below the given threshold.',
        'input_schema' => array(
            'type'       => 'object',
            'properties' => array(
                'threshold' => array(
                    'type'        => 'integer',
                    'description' => 'Stock quantity cutoff',
                    'default'     => 5,
                ),
            ),
        ),
        'output_schema' => array(
            'type'  => 'array',
            'items' => array(
                'type'       => 'object',
                'properties' => array(
                    'id'             => array( 'type' => 'integer' ),
                    'name'           => array( 'type' => 'string' ),
                    'stock_quantity' => array( 'type' => 'integer' ),
                ),
            ),
        ),
        'execute_callback' => function( $args ) {
            $products = wc_get_products( array(
                'status'         => 'publish',
                'manage_stock'   => true,
                'stock_status'   => 'instock',
                'stock_quantity' => $args['threshold'] ?? 5,
                'limit'          => 50,
            ) );
            return array_map( function( $p ) {
                return array(
                    'id'             => $p->get_id(),
                    'name'           => $p->get_name(),
                    'stock_quantity' => $p->get_stock_quantity(),
                );
            }, $products );
        },
        'permission_callback' => function() {
            return current_user_can( 'manage_woocommerce' );
        },
    ) );
} );

Because the ability namespace is your-store/ rather than woocommerce/, WooCommerce’s MCP server will not include it automatically. You need to hook into the inclusion filter:

add_filter( 'woocommerce_mcp_include_ability', function( $include, $ability_id ) {
    if ( str_starts_with( $ability_id, 'your-store/' ) ) {
        return true;
    }
    return $include;
}, 10, 2 );

After deploying this code, any connected MCP client can call your-store/low-stock-check with a threshold parameter and receive a typed JSON array. The input and output schemas give the AI enough context to call the ability correctly without additional prompting.

Security Considerations for MCP Endpoints

Exposing store operations to AI agents introduces the same risks as any API surface – unauthorized access, injection vulnerabilities, and data leakage. WooCommerce MCP leans on existing REST API key authentication, but that alone does not cover every threat vector.

Start with least-privilege scoping. If the AI only needs to read data, issue a Read-only API key. Write access should be reserved for specific workflows like inventory updates, and even then, consider generating a separate key pair with a narrow permission set. Two-factor authentication on admin accounts adds another layer – if an API key is compromised, the attacker still cannot escalate to full admin access. HTTPS is mandatory for production MCP endpoints. The proxy will happily connect over plain HTTP during local development, but WooCommerce provides a filter to block insecure transport explicitly:

add_filter( 'woocommerce_mcp_allow_insecure_transport', '__return_false' );

Order and customer operations return PII – names, emails, shipping addresses, payment method identifiers. Evaluate whether your AI workflow actually needs this data. A product recommendation agent does not need customer addresses, so restricting the exposed abilities to product-scoped operations reduces the blast radius of a potential breach. The permission_callback in each registered ability gives you fine-grained control over which user roles and capabilities can trigger specific tools.

Extending MCP With Webhooks and External Systems

The Abilities API is not limited to REST endpoint bridging. Abilities can trigger webhook dispatches, call external APIs, or run direct database queries. A shipping label generation ability, for example, could call a carrier’s API inside its execute_callback, return a tracking URL, and let the AI present it in a natural-language response.

Combining MCP with local LLM-driven product recommendations creates a feedback loop where the AI queries your store catalog, runs inference locally, and writes recommendations back through a write-enabled ability. The WP-CLI integration also supports STDIO transport, meaning you can run the MCP adapter directly from the command line for scripting and automation without the HTTP proxy.

Debugging and Troubleshooting MCP Connections

When the MCP server does not respond or returns unexpected errors, start with the WooCommerce logs. Navigate to WooCommerce > Status > Logs and filter for entries with the woocommerce-mcp source. Common issues fall into three categories.

Authentication failures show up when the API key format is wrong. The key must follow the pattern consumer_key:consumer_secret with a colon separator – no spaces, no URL encoding. Ability-not-found errors mean the ability was either not registered during the abilities_api_init hook or the namespace was excluded by the inclusion filter. Proxy connection failures typically trace back to Node.js version mismatches with npx or SSL certificate problems on local development environments. The WordPress API landscape continues to evolve alongside MCP, so keeping your proxy package and WooCommerce version in sync avoids most compatibility issues.

MCP Inspector is another option for debugging. Running npx @modelcontextprotocol/inspector with your environment variables lets you send raw MCP calls and inspect responses without going through an AI client, which isolates whether the issue is in the proxy, the server, or the client’s interpretation of the response.

Често задавани въпроси