docs/features/mcp/README.md
WooCommerce includes native support for the Model Context Protocol (MCP), enabling AI assistants and tools to interact directly with WooCommerce stores through a standardized protocol. This integration exposes WooCommerce functionality as discoverable tools that AI clients can use to perform store operations with proper authentication and permissions.
:::info
Developer Preview Notice The MCP implementation in WooCommerce is currently in developer preview. Implementation details, APIs, and integration patterns may change in future releases as the feature matures.
:::
The Model Context Protocol (MCP) is an open standard that enables AI applications to securely connect to external data sources and tools. WooCommerce's MCP integration builds on two core technologies:
This architecture allows WooCommerce to expose operations as MCP tools through the flexible WordPress Abilities system while maintaining existing security and permission models.
WooCommerce registers purpose-built abilities for core store operations. These abilities are available through the WordPress Abilities API and can be surfaced through the shared WordPress MCP adapter.
The deprecated WooCommerce MCP endpoint also exposes REST-derived compatibility abilities for products and orders. These abilities map to existing REST API operations and currently include product list, retrieve, create, update, and delete operations, plus order list, retrieve, create, and update operations.
All operations respect WooCommerce's existing permission system. The deprecated WooCommerce MCP endpoint authenticates using WooCommerce REST API keys; clients using the shared WordPress MCP adapter should follow the adapter's authentication requirements.
:::warning
Data Privacy Notice Order and customer operations may expose personally identifiable information (PII) including names, email addresses, physical addresses, and payment details. You are responsible for ensuring compliance with applicable data protection regulations. Use least-privilege API scopes, rotate and revoke REST API keys regularly, and follow your organization's data retention and handling policies.
:::
The MCP integration uses a multi-layered architecture to bridge between MCP clients and WordPress:
AI Client (Claude, etc.)
↓ (MCP protocol over stdio/JSON-RPC)
Local MCP Proxy (mcp-wordpress-remote)
↓ (HTTP/HTTPS requests with authentication)
Remote WordPress MCP Server (mcp-adapter)
↓ (WordPress Abilities API)
WooCommerce Abilities
↓ (REST API calls or direct operations)
WooCommerce Core
Local MCP Proxy (mcp-wordpress-remote)
Remote WordPress MCP Server (mcp-adapter)
/wp-json/woocommerce/mcp endpoint for WooCommerce compatibilityMCP Adapter Provider (MCPAdapterProvider.php)
mcp_integration feature flag is enabledmcp_integration)Abilities Registry (AbilitiesRegistry.php)
Purpose-Built Domain Abilities (Domain)
mcp.public and mcp.type) for MCP exposureREST Bridge Implementation (AbilitiesRestBridge.php)
expose_in_deprecated_woocommerce_mcp metadataWooCommerce Transport (WooCommerceRestTransport.php)
WooCommerce's preferred implementation path is purpose-built domain abilities. These abilities use schemas and response shapes designed for agent workflows instead of automatically projecting every REST-shaped operation into MCP.
REST-derived abilities remain available as a compatibility layer for the deprecated WooCommerce MCP endpoint. This keeps existing clients working while allowing new abilities to use the shared WordPress MCP adapter without expanding the deprecated endpoint by namespace alone.
The MCP feature is controlled by the mcp_integration feature flag. You can enable it programmatically:
add_filter( 'woocommerce_features', function( $features ) {
$features['mcp_integration'] = true;
return $features;
});
Alternatively, you can enable it via WooCommerce CLI:
wp option update woocommerce_feature_mcp_integration_enabled yes
The deprecated WooCommerce MCP endpoint authenticates using WooCommerce REST API keys in the X-MCP-API-Key header:
X-MCP-API-Key: ck_your_consumer_key:cs_your_consumer_secret
To create API keys:
read, write, or read_write)Requests to the deprecated WooCommerce MCP endpoint require HTTPS by default. For local development, you can disable this requirement:
add_filter( 'woocommerce_mcp_allow_insecure_transport', '__return_true' );
For the deprecated WooCommerce MCP endpoint, the transport layer validates operations against API key permissions:
read permissions: Allow GET requestswrite permissions: Allow POST, PUT, PATCH, DELETE requestsread_write permissions: Allow all operationsThe deprecated WooCommerce MCP server is available at:
https://yourstore.com/wp-json/woocommerce/mcp
The examples below configure clients to use the deprecated WooCommerce MCP endpoint.
The current MCP implementation uses a local proxy approach to connect MCP clients with WordPress servers:
@automattic/mcp-wordpress-remote) runs on your machine and translates MCP protocol messages to HTTP requestsThis proxy pattern is commonly used in MCP integrations to bridge protocol differences and handle authentication. The mcp-wordpress-remote package acts as a protocol translator, converting the stdio-based MCP communication that clients expect into the HTTP REST API calls that WordPress understands.
Future Evolution: While this proxy approach provides a robust foundation, future implementations may explore direct MCP protocol support within WordPress or alternative connection methods as the MCP ecosystem evolves.
To connect Claude Code to your WooCommerce MCP server:
claude mcp add woocommerce_mcp \
--env WP_API_URL=https://yourstore.com/wp-json/woocommerce/mcp \
--env CUSTOM_HEADERS='{"X-MCP-API-Key": "YOUR_CONSUMER_KEY:YOUR_CONSUMER_SECRET"}' \
-- npx -y @automattic/mcp-wordpress-remote@latest
For other MCP clients, add this configuration to your MCP settings. This configuration tells the MCP client to run the mcp-wordpress-remote proxy locally, which will handle the communication with your WordPress server:
{
"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\": \"YOUR_CONSUMER_KEY:YOUR_CONSUMER_SECRET\"}"
}
}
}
}
Important: Replace YOUR_CONSUMER_KEY:YOUR_CONSUMER_SECRET with your actual WooCommerce API credentials.
Troubleshooting: For common setup issues with npx versions or SSL in local environments, see the mcp-wordpress-remote troubleshooting guide.
Third-party plugins can register additional abilities using the WordPress Abilities API. Abilities can be implemented in various ways, including direct operations, custom logic, REST endpoint bridging, or external integrations.
Register an ability category first, then register the ability during the WordPress Abilities API init hook:
add_action( 'wp_abilities_api_categories_init', function() {
if ( ! function_exists( 'wp_register_ability_category' ) ) {
return;
}
if ( function_exists( 'wp_has_ability_category' ) && wp_has_ability_category( 'your-plugin' ) ) {
return;
}
wp_register_ability_category(
'your-plugin',
array(
'label' => __( 'Your Plugin', 'your-plugin' ),
'description' => __( 'Abilities provided by Your Plugin.', 'your-plugin' ),
)
);
});
add_action( 'wp_abilities_api_init', function() {
if ( ! function_exists( 'wp_register_ability' ) ) {
return;
}
wp_register_ability(
'your-plugin/custom-operation',
array(
'label' => __( 'Custom Store Operation', 'your-plugin' ),
'description' => __( 'Performs a custom store operation.', 'your-plugin' ),
'category' => 'your-plugin',
'execute_callback' => 'your_custom_ability_handler',
'permission_callback' => function () {
return current_user_can( 'manage_woocommerce' );
},
'input_schema' => array(
'type' => 'object',
'properties' => array(
'store_id' => array(
'type' => 'integer',
'description' => 'Store identifier',
),
),
'required' => array( 'store_id' ),
),
'output_schema' => array(
'type' => 'object',
'properties' => array(
'success' => array(
'type' => 'boolean',
'description' => 'Operation result',
),
),
),
'meta' => array(
'show_in_rest' => true,
'mcp' => array(
'public' => true,
'type' => 'tool',
),
),
)
);
});
The mcp.public and mcp.type metadata tells the shared WordPress MCP adapter that the ability can be exposed as an MCP tool. The show_in_rest metadata exposes the ability through the Abilities API REST routes.
REST-derived WooCommerce abilities include expose_in_deprecated_woocommerce_mcp metadata automatically. Custom abilities are not included by namespace alone; set this metadata to boolean true when registering the ability to include it in the deprecated WooCommerce MCP server by default:
'meta' => array(
'show_in_rest' => true,
'mcp' => array(
'public' => true,
'type' => 'tool',
),
'expose_in_deprecated_woocommerce_mcp' => true,
),
To override the default metadata decision at runtime, use the woocommerce_mcp_include_ability filter:
add_filter( 'woocommerce_mcp_include_ability', function( $include, $ability_id ) {
if ( str_starts_with( $ability_id, 'your-plugin/' ) ) {
return true;
}
return $include;
}, 10, 2 );
For a complete working example, see the WooCommerce MCP Ability Demo Plugin. This demonstration plugin shows how third-party developers can:
The demo plugin creates a woocommerce-demo/store-info ability that retrieves store information and statistics, demonstrating the integration patterns for extending WooCommerce MCP capabilities while using a direct implementation approach rather than REST endpoint bridging.
mcp_integration feature flag is enabledconsumer_key:consumer_secretwp_abilities_api_categories_initwp_abilities_api_initexpose_in_deprecated_woocommerce_mcp metadata or override inclusion using the woocommerce_mcp_include_ability filterCheck WooCommerce → Status → Logs for entries with source woocommerce-mcp.