Labsco
Automattic logo

WordPress MCP

★ 3

from Automattic

A Python MCP server for interacting with a local WordPress instance.

🔥✓ VerifiedFreeQuick setup
#automation#git

This repository will be deprecated as the mcp-adapter AI Building Block for WordPress continues releasing stable versions.

The shift aligns with two important developments:

  • The 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

A comprehensive WordPress plugin that implements the Model Context Protocol (MCP) 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

ProtocolEndpointFormatAuthenticationUse Case
STDIO/wp/v2/wpmcpWordPress-styleJWT + App PasswordsLegacy compatibility
Streamable/wp/v2/wpmcp/streamableJSON-RPC 2.0JWT onlyModern AI clients

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
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
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:

# 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

# 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.

Documentation

Support

For support and questions: