Readme.md•16.3 kB
This repository will be deprecated as the [mcp-adapter](https://github.com/wordpress/mcp-adapter) AI Building Block for WordPress continues releasing stable versions.
The shift aligns with two important developments:
- The [Abilities API](https://github.com/WordPress/abilities-api) is moving into WordPress Core as of version 6.9.
- mcp-adapter is now stable and will become the canonical plugin and Composer package for MCP integration in WordPress.
We encourage all users to migrate to mcp-adapter. Future work, including new features and fixes, will happen there. This repository will remain available in archived form for historical reference.
# WordPress MCP
[](https://github.com/Automattic/wordpress-mcp/releases)
A comprehensive WordPress plugin that implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) to expose WordPress functionality through standardized interfaces. This plugin enables AI models and applications to interact with WordPress sites securely using multiple transport protocols and enterprise-grade authentication.
## Features
- **Dual Transport Protocols**: STDIO and HTTP-based (Streamable) transports
- **JWT Authentication**: Secure token-based authentication with management UI
- **Admin Interface**: React-based token management and settings dashboard
- **AI-Friendly APIs**: JSON-RPC 2.0 compliant endpoints for AI integration
- **Extensible Architecture**: Custom tools, resources, and prompts support
- **WordPress Feature API**: Adapter for standardized WordPress functionality
- **Experimental REST API CRUD Tools**: Generic tools for any WordPress REST API endpoint
- **Comprehensive Testing**: 200+ test cases covering all protocols and authentication
- **High Performance**: Optimized routing and caching mechanisms
- **Enterprise Security**: Multi-layer authentication and audit logging
## Architecture
The plugin implements a dual transport architecture:
```
WordPress MCP Plugin
├── Transport Layer
│ ├── McpStdioTransport (/wp/v2/wpmcp)
│ └── McpStreamableTransport (/wp/v2/wpmcp/streamable)
├── Authentication
│ └── JWT Authentication System
├── Method Handlers
│ ├── Tools, Resources, Prompts
│ └── System & Initialization
└── Admin Interface
└── React-based Token Management
```
### Transport Protocols
| Protocol | Endpoint | Format | Authentication | Use Case |
| -------------- | ------------------------- | --------------- | ------------------- | -------------------- |
| **STDIO** | `/wp/v2/wpmcp` | WordPress-style | JWT + App Passwords | Legacy compatibility |
| **Streamable** | `/wp/v2/wpmcp/streamable` | JSON-RPC 2.0 | JWT only | Modern AI clients |
## Installation
### Quick Install
1. Download `wordpress-mcp.zip` from [releases](https://github.com/Automattic/wordpress-mcp/releases/)
2. Upload to `/wp-content/plugins/wordpress-mcp` directory
3. Activate through WordPress admin 'Plugins' menu
4. Navigate to `Settings > WordPress MCP` to configure
### Composer Install (Development)
```bash
cd wp-content/plugins/
git clone https://github.com/Automattic/wordpress-mcp.git
cd wordpress-mcp
composer install --no-dev
npm install && npm run build
```
## Authentication Setup
### JWT Token Generation
1. Go to `Settings > WordPress MCP > Authentication Tokens`
2. Select token duration (1-24 hours)
3. Click "Generate New Token"
4. Copy the token for use in your MCP client
### MCP Client Configuration
#### Claude Desktop Configuration using [mcp-wordpress-remote](https://github.com/Automattic/mcp-wordpress-remote) proxy
Add to your Claude Desktop `claude_desktop_config.json`:
```json
{
"mcpServers": {
"wordpress-mcp": {
"command": "npx",
"args": [ "-y", "@automattic/mcp-wordpress-remote@latest" ],
"env": {
"WP_API_URL": "https://your-site.com/",
"JWT_TOKEN": "your-jwt-token-here",
"LOG_FILE": "optional-path-to-log-file"
}
}
}
}
```
#### Using Application Passwords (Alternative)
```json
{
"mcpServers": {
"wordpress-mcp": {
"command": "npx",
"args": [ "-y", "@automattic/mcp-wordpress-remote@latest" ],
"env": {
"WP_API_URL": "https://your-site.com/",
"WP_API_USERNAME": "your-username",
"WP_API_PASSWORD": "your-application-password",
"LOG_FILE": "optional-path-to-log-file"
}
}
}
}
```
#### VS Code MCP Extension (Direct Streamable Transport)
Add to your VS Code MCP settings:
```json
{
"servers": {
"wordpress-mcp": {
"type": "http",
"url": "https://your-site.com/wp-json/wp/v2/wpmcp/streamable",
"headers": {
"Authorization": "Bearer your-jwt-token-here"
}
}
}
}
```
#### MCP Inspector (Development/Testing)
```bash
# Using JWT Token with proxy
npx @modelcontextprotocol/inspector \
-e WP_API_URL=https://your-site.com/ \
-e JWT_TOKEN=your-jwt-token-here \
npx @automattic/mcp-wordpress-remote@latest
# Using Application Password with proxy
npx @modelcontextprotocol/inspector \
-e WP_API_URL=https://your-site.com/ \
-e WP_API_USERNAME=your-username \
-e WP_API_PASSWORD=your-application-password \
npx @automattic/mcp-wordpress-remote@latest
```
#### Local Development Configuration
```json
{
"mcpServers": {
"wordpress-local": {
"command": "node",
"args": [ "/path/to/mcp-wordpress-remote/dist/proxy.js" ],
"env": {
"WP_API_URL": "http://localhost:8080/",
"JWT_TOKEN": "your-local-jwt-token",
"LOG_FILE": "optional-path-to-log-file"
}
}
}
}
```
## Usage
### With MCP Clients
This plugin works seamlessly with MCP-compatible clients in two ways:
**Via Proxy:**
- [mcp-wordpress-remote](https://github.com/Automattic/mcp-wordpress-remote) - Official MCP client with enhanced features
- Claude Desktop with proxy configuration for full WordPress and WooCommerce support
- Any MCP client using the STDIO transport protocol
**Direct Streamable Transport:**
- VS Code MCP Extension connecting directly to `/wp/v2/wpmcp/streamable`
- Custom HTTP-based MCP implementations using JSON-RPC 2.0
- Any client supporting HTTP transport with JWT authentication
The streamable transport provides a direct JSON-RPC 2.0 compliant endpoint, while the proxy offers additional features like WooCommerce integration, enhanced logging, and compatibility with legacy authentication methods.
### Available MCP Methods
| Method | Description | Transport Support |
| ---------------- | ------------------------ | ----------------- |
| `initialize` | Initialize MCP session | Both |
| `tools/list` | List available tools | Both |
| `tools/call` | Execute a tool | Both |
| `resources/list` | List available resources | Both |
| `resources/read` | Read resource content | Both |
| `prompts/list` | List available prompts | Both |
| `prompts/get` | Get prompt template | Both |
### Experimental REST API CRUD Tools
**EXPERIMENTAL FEATURE**: This functionality is experimental and may change or be removed in future versions.
When enabled via `Settings > WordPress MCP > Enable REST API CRUD Tools`, the plugin provides three powerful generic tools that can interact with any WordPress REST API endpoint:
#### Available Tools
| Tool Name | Description | Type |
| ---------------------- | --------------------------------------------------- | ------ |
| `list_api_functions` | Discover all available WordPress REST API endpoints | Read |
| `get_function_details` | Get detailed metadata for specific endpoint/method | Read |
| `run_api_function` | Execute any REST API function with CRUD operations | Action |
#### Usage Workflow
1. **Discovery**: Use `list_api_functions` to see all available endpoints
2. **Inspection**: Use `get_function_details` to understand required parameters
3. **Execution**: Use `run_api_function` to perform CRUD operations
#### Security & Permissions
- **User Capabilities**: All operations respect current user permissions
- **Settings Control**: Individual CRUD operations can be disabled in settings:
- Enable Create Tools (POST operations)
- Enable Update Tools (PATCH/PUT operations)
- Enable Delete Tools (DELETE operations)
- **Automatic Filtering**: Excludes sensitive endpoints (JWT auth, oembed, autosaves, revisions)
#### Benefits
- **Universal Access**: Works with any WordPress REST API endpoint, including custom post types and third-party plugins
- **AI-Friendly**: Provides discovery and introspection capabilities for AI agents
- **Standards Compliant**: Uses standard HTTP methods (GET, POST, PATCH, DELETE)
- **Permission Safe**: Inherits WordPress user capabilities and respects endpoint permissions
## Development
### Project Structure
```
wp-content/plugins/wordpress-mcp/
├── includes/ # PHP classes
│ ├── Core/ # Transport and core logic
│ ├── Auth/ # JWT authentication
│ ├── Tools/ # MCP tools
│ ├── Resources/ # MCP resources
│ ├── Prompts/ # MCP prompts
│ └── Admin/ # Settings interface
├── src/ # React components
│ └── settings/ # Admin UI components
├── tests/ # Test suite
│ └── phpunit/ # PHPUnit tests
└── docs/ # Documentation
```
### Adding Custom Tools
You can extend the MCP functionality by adding custom tools through your own plugins or themes. Create a new tool class in your plugin or theme:
```php
<?php
declare(strict_types=1);
namespace Automattic\WordpressMcp\Tools;
class MyCustomTool {
public function register(): void {
add_action('wp_mcp_register_tools', [$this, 'register_tool']);
}
public function register_tool(): void {
WPMCP()->register_tool([
'name' => 'my_custom_tool',
'description' => 'My custom tool description',
'inputSchema' => [
'type' => 'object',
'properties' => [
'param1' => ['type' => 'string', 'description' => 'Parameter 1']
],
'required' => ['param1']
],
'callback' => [$this, 'execute'],
]);
}
public function execute(array $args): array {
// Your tool logic here
return ['result' => 'success'];
}
}
```
### Adding Custom Resources
You can extend the MCP functionality by adding custom resources through your own plugins or themes. Create a new resource class in your plugin or theme:
```php
<?php
declare(strict_types=1);
namespace Automattic\WordpressMcp\Resources;
class MyCustomResource {
public function register(): void {
add_action('wp_mcp_register_resources', [$this, 'register_resource']);
}
public function register_resource(): void {
WPMCP()->register_resource([
'uri' => 'custom://my-resource',
'name' => 'My Custom Resource',
'description' => 'Custom resource description',
'mimeType' => 'application/json',
'callback' => [$this, 'get_content'],
]);
}
public function get_content(): array {
return ['contents' => [/* resource data */]];
}
}
```
### Testing
Run the comprehensive test suite:
```bash
# Run all tests
vendor/bin/phpunit
# Run specific test suites
vendor/bin/phpunit tests/phpunit/McpStdioTransportTest.php
vendor/bin/phpunit tests/phpunit/McpStreamableTransportTest.php
vendor/bin/phpunit tests/phpunit/JwtAuthTest.php
# Run with coverage
vendor/bin/phpunit --coverage-html coverage/
```
### Building Frontend
```bash
# Development build
npm run dev
# Production build
npm run build
# Watch mode
npm run start
```
## Security
### Best Practices
- **Token Management**: Use shortest expiration time needed (1-24 hours)
- **User Permissions**: Tokens inherit user capabilities
- **Secure Storage**: Never commit tokens to repositories
- **Regular Cleanup**: Revoke unused tokens promptly
- **Access Control**: Streamable transport requires admin privileges
- **CRUD Operations**: Only enable create/update/delete tools when necessary
- **Experimental Features**: Use REST API CRUD tools with caution in production environments
### Security Features
- JWT signature validation
- Token expiration and revocation
- User capability inheritance
- Secure secret key generation
- Audit logging for security events
- Protection against malformed requests
## Testing Coverage
The plugin includes extensive testing:
- **Transport Testing**: Both STDIO and Streamable protocols
- **Authentication Testing**: JWT generation, validation, and revocation
- **Integration Testing**: Cross-transport comparison
- **Security Testing**: Edge cases and malformed requests
- **Performance Testing**: Load and stress testing
View detailed testing documentation in [`tests/README.md`](tests/README.md).
## Configuration
### Environment Variables
```php
// wp-config.php
define('WPMCP_JWT_SECRET_KEY', 'your-secret-key');
define('WPMCP_DEBUG', true); // Enable debug logging
```
### Plugin Settings
Access via `Settings > WordPress MCP`:
- **Enable/Disable MCP**: Toggle plugin functionality
- **Transport Configuration**: Configure STDIO/Streamable transports
- **Feature Toggles**: Enable/disable specific tools and resources
- **CRUD Operation Controls**: Granular control over create, update, and delete operations
- **Experimental Features**: Enable REST API CRUD Tools (experimental functionality)
- **Authentication Settings**: JWT token management
#### CRUD Operation Settings
The plugin provides granular control over CRUD operations:
- **Enable Create Tools**: Allow POST operations via MCP tools
- **Enable Update Tools**: Allow PATCH/PUT operations via MCP tools
- **Enable Delete Tools**: ⚠️ Allow DELETE operations via MCP tools (use with caution)
- **Enable REST API CRUD Tools**: 🧪 Enable experimental generic REST API access tools
**Security Note**: Delete operations can permanently remove data. Only enable delete tools if you trust all users with MCP access.
## Contributing
We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md).
### Development Setup
1. Clone the repository
2. Run `composer install` for PHP dependencies
3. Run `npm install` for JavaScript dependencies
4. Set up WordPress test environment
5. Run tests with `vendor/bin/phpunit`
## Documentation
- **Documentation Overview**: [docs/README.md](docs/README.md)
- **Client Setup Guide**: [docs/client-setup.md](docs/client-setup.md)
- **AI Integration Guide**: [docs/for-ai.md](docs/for-ai.md)
- **Registered Tools**: [docs/registered-tools.md](docs/registered-tools.md)
- **Registered Resources**: [docs/registered-resources.md](docs/registered-resources.md)
- **Registered Prompts**: [docs/registered-prompts.md](docs/registered-prompts.md)
- **Register MCP Tools**: [docs/register-mcp-tools.md](docs/register-mcp-tools.md)
- **Register MCP Prompts**: [docs/register-mcp-prompt.md](docs/register-mcp-prompt.md)
- **Register MCP Resources**: [docs/register-mcp-resources.md](docs/register-mcp-resources.md)
- **Troubleshooting Guide**: [docs/troubleshooting.md](docs/troubleshooting.md)
- **Testing Guide**: [tests/README.md](tests/README.md)
## Support
For support and questions:
- **Documentation**: [docs/README.md](docs/README.md)
- **Bug Reports**: [GitHub Issues](https://github.com/Automattic/wordpress-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/Automattic/wordpress-mcp/discussions)
- **Contact**: Reach out to the maintainers
## License
This project is licensed under the [GPL v2 or later](LICENSE).
---
Built with ❤️ by [Automattic](https://automattic.com) for the WordPress and AI communities.