MCP WordPress Remote

A Model Context Protocol (MCP) server for seamless WordPress integration

Connect AI assistants like Claude Desktop to your WordPress sites with multiple authentication methods including OAuth 2.0, JWT tokens, and application passwords.

Features

• MCP Authorization Specification Compliant - Implements MCP Authorization specification 2025-06-18
• OAuth 2.1 with PKCE - Secure authorization code flow with PKCE (RFC 7636)
• Resource Indicators - RFC 8707 compliance for token audience binding
• Dynamic Client Registration - RFC 7591 support for automatic client registration
• Protected Resource Metadata Discovery - RFC 9728 for automatic endpoint discovery
• Multiple Authentication Methods - OAuth 2.1, JWT tokens, and WordPress application passwords
• Persistent Token Storage - OAuth tokens stored securely with automatic validation
• Multi-instance Coordination - Lockfiles prevent authentication conflicts
• Automatic Token Management - Handles validation, refresh, and cleanup
• Enhanced Error Handling - Detailed error messages with proper categorization
• Comprehensive Logging - Structured logging with categories and levels
• Complete MCP Support - Tools, resources, prompts, and more

Quick Start

Installation

npm install @automattic/mcp-wordpress-remote

Configuration

Add to your MCP client configuration (e.g., Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote"],
      "env": {
        "WP_API_URL": "https://your-wordpress-site.com"
      }
    }
  }
}

Custom Headers

You can add custom headers to all API requests using the CUSTOM_HEADERS environment variable. This is useful for API keys, custom authentication, or other header requirements.

JSON Format (Recommended):

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote"],
      "env": {
        "WP_API_URL": "https://your-wordpress-site.com",
        "CUSTOM_HEADERS": "{"X-MCP-API-Key": "*Ibo7tweixlbfuwaiufxgakjyefctwajcetb*", "X-Custom-Header": "value"}"
      }
    }
  }
}

Comma-Separated Format:

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote"],
      "env": {
        "WP_API_URL": "https://your-wordpress-site.com",
        "CUSTOM_HEADERS": "X-MCP-API-Key:IOskncfyes78U8on3q7ry43o487tybrc,X-Custom-Header:value"
      }
    }
  }
}

Command Line Usage:

CUSTOM_HEADERS='{"X-MCP-API-Key": "wc_mcp_FaQduhQcW0mfVaZgP3yaaqDuXaZ3mw7j"}' \
WP_API_URL="https://your-site.com" \
npx @automattic/mcp-wordpress-remote

Custom headers are included in:

• All WordPress API requests
• OAuth discovery requests
• OAuth token exchange requests
• OAuth client registration requests

First Run

1. Start your MCP client (Claude Desktop, etc.)
2. Choose authentication method based on your preference:
   • OAuth 2.0 (default): Browser opens automatically for authorization
   • JWT Token: Set JWT_TOKEN environment variable
   • Application Password: Set WP_API_USERNAME and WP_API_PASSWORD
3. Start using WordPress features in your AI assistant

WordPress MCP Plugin

You need to install the wordpress-mcp plugin on your WordPress website and enable MCP Functionality in Settings > MCP Settings.

Authentication Methods

1. OAuth 2.1 (Recommended - MCP Compliant)

OAuth 2.1 provides the most secure and user-friendly experience with full MCP Authorization specification compliance.

For Self-Hosted WordPress Sites:

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote"],
      "env": {
        "WP_API_URL": "https://your-wordpress-site.com",
        "OAUTH_ENABLED": "true"
      }
    }
  }
}

MCP Authorization Specification Features:

• OAuth 2.1 authorization code flow with PKCE (RFC 7636)
• Resource Indicators (RFC 8707) for token audience binding
• Dynamic Client Registration (RFC 7591) when supported
• Protected Resource Metadata Discovery (RFC 9728)
• Authorization Server Metadata Discovery (RFC 8414)

Benefits:

• Full compliance with MCP Authorization specification 2025-06-18
• Enhanced security with PKCE protection
• One-time browser authorization
• Tokens stored securely with automatic validation
• Automatic endpoint discovery
• No need to manage passwords
• Automatic expiration handling

2. JWT Token Authentication

For server-to-server authentication or when OAuth is not available.

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote"],
      "env": {
        "WP_API_URL": "https://your-wordpress-site.com",
        "JWT_TOKEN": "your-jwt-token-here"
      }
    }
  }
}

3. WordPress Application Passwords (Legacy)

Uses WordPress username and application password for basic authentication.

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote"],
      "env": {
        "WP_API_URL": "https://your-wordpress-site.com",
        "WP_API_USERNAME": "your-username",
        "WP_API_PASSWORD": "your-application-password",
        "OAUTH_ENABLED": "false"
      }
    }
  }
}

To create an application password:

1. Go to your WordPress admin dashboard
2. Navigate to Users > Profile
3. Scroll down to "Application Passwords"
4. Create a new application password for MCP access

Advanced Configuration

Custom OAuth Settings

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote"],
      "env": {
        "WP_API_URL": "https://your-wordpress-site.com",
        "OAUTH_CALLBACK_PORT": "7665",
        "OAUTH_HOST": "127.0.0.1",
        "WP_OAUTH_CLIENT_ID": "your-custom-client-id"
      }
    }
  }
}

WooCommerce Integration

For WooCommerce-specific tools and reports:

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote"],
      "env": {
        "WP_API_URL": "https://your-wordpress-site.com",
        "WOO_CUSTOMER_KEY": "ck_your-consumer-key",
        "WOO_CUSTOMER_SECRET": "cs_your-consumer-secret"
      }
    }
  }
}

Environment Variables

---