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's MCP integration provides AI assistants with structured access to core store operations:
All operations respect WooCommerce's existing permission system and are authenticated using WooCommerce REST API keys.
:::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 endpointMCP Adapter Provider (MCPAdapterProvider.php)
mcp_integration)Abilities Registry (AbilitiesRegistry.php)
REST Bridge Implementation (AbilitiesRestBridge.php)
WooCommerce Transport (WooCommerceRestTransport.php)
For this developer preview, WooCommerce abilities are implemented by bridging to existing REST API endpoints. This approach allows us to quickly expose core functionality while leveraging proven REST controllers. However, the WordPress Abilities API is designed to be flexible - abilities can be implemented in various ways beyond REST endpoint proxying, including direct database operations, custom business logic, or integration with external services.
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
MCP clients authenticate 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)MCP requests require HTTPS by default. For local development, you can disable this requirement:
add_filter( 'woocommerce_mcp_allow_insecure_transport', '__return_true' );
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 WooCommerce MCP server is available at:
https://yourstore.com/wp-json/woocommerce/mcp
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 - REST endpoint bridging, direct operations, custom logic, or external integrations. Here's a basic example:
add_action( 'abilities_api_init', function() {
wp_register_ability(
'your-plugin/custom-operation',
array(
'label' => __( 'Custom Store Operation', 'your-plugin' ),
'description' => __( 'Performs a custom store operation.', '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'
)
)
)
)
);
});
By default, only abilities with the woocommerce/ namespace are included. To include abilities from other namespaces:
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_secretabilities_api_initwoocommerce_mcp_include_ability filterCheck WooCommerce → Status → Logs for entries with source woocommerce-mcp.