🚀 WordPress Model Context Protocol (MCP) Server

English Documentation | راهنمای فارسی (Persian)

A high-performance, enterprise-grade Model Context Protocol (MCP) server connecting WordPress sites directly to modern AI agents (Claude Code, Cursor, Google Antigravity, Windsurf, etc.).

Designed with a Dual-Engine Architecture and Zero-Trust Security Guard, it allows AI agents to inspect site health, query posts and pages, explore ACF & custom post types, optimize SEO, and manage content safely without exposing your site to hacks or prompt injection vulnerabilities.

🏗 Architecture Overview

                   ┌─────────────────────────────────────────┐
                   │  AI Agents (Claude Code, Cursor, AGY)   │
                   └────────────────────┬────────────────────┘
                                        │  JSON-RPC / Stdio
                                        ▼
             ┌─────────────────────────────────────────────────────┐
             │                wordpress-mcp Server                 │
             │   ┌──────────────────────────────────────────────┐  │
             │   │    Zero-Trust Security Guard (Safe Mode)     │  │
             │   └──────────────────────┬───────────────────────┘  │
             └──────────────────────────┼──────────────────────────┘
                                        │
                    ┌───────────────────┴───────────────────┐
                    ▼                                       ▼
        ┌───────────────────────┐               ┌───────────────────────┐
        │     WpCliEngine       │               │      WpRestEngine     │
        │   (LocalWP / CLI)     │               │ (Remote REST + Auth)  │
        └───────────┬───────────┘               └───────────┬───────────┘
                    │                                       │
                    ▼                                       ▼
         [ Local Development ]                    [ Live Production ]
       LocalWP, Docker, Valet                    WordPress REST API

Related MCP server: Agent Abilities for MCP

🌟 Key Features

• Dual-Engine Flexibility:

  • Local Engine (cli): Connects with zero latency to local installations (LocalWP, Valet, Docker, native WP-CLI) with automatic PHP error and notice filtering.

  • Remote Engine (rest): Securely interfaces with remote production or staging sites over HTTPS via standard WordPress Application Passwords.

• Zero-Trust Security Guard:

  • Read-Only by Default: All state-mutating actions (wp_create_post, wp_update_post) are blocked unless explicitly allowed via --allow-write or SAFE_MODE=false.

  • No Raw Eval / No Raw SQL: The AI interacts exclusively through strictly validated, typed Zod schemas.

  • Input Sanitization: Automatically strips null bytes and malicious control characters.

  • Audit Logging: Optional audit trail logs every single invocation and argument set with timestamps.

• Built-in Interactive Web Playground:

  • Includes an embedded web playground (npm run dashboard) running on http://localhost:3300 for visual verification and multi-site toggling.

🛠 Available Tools

🚀 Quick Start

1. Installation

git clone https://github.com/am333ni7y/wordpress-mcp.git
cd wordpress-mcp
npm install
npm run build

⚙️ Client Configurations

A. Cursor (~/.cursor/mcp.json)

Add the server to your Cursor MCP settings:

For Local Sites (LocalWP / WP-CLI):

{
  "mcpServers": {
    "wordpress-local": {
      "command": "node",
      "args": [
        "/absolute/path/to/wordpress-mcp/dist/index.js",
        "--path", "/path/to/wordpress/site",
        "--adapter", "cli"
      ]
    }
  }
}

For Remote Sites (REST API):

{
  "mcpServers": {
    "wordpress-live": {
      "command": "node",
      "args": [
        "/absolute/path/to/wordpress-mcp/dist/index.js",
        "--adapter", "rest",
        "--url", "https://your-site.com",
        "--username", "your_admin_user",
        "--password", "xxxx xxxx xxxx xxxx"
      ]
    }
  }
}

How to create an Application Password: In your WordPress admin, go to Users > Profile, scroll to Application Passwords, enter a name (e.g. Cursor-MCP), and click Add New Application Password.

B. Claude Code CLI

# For Local Sites
claude mcp add wp-local node /absolute/path/to/wordpress-mcp/dist/index.js -- --path "/path/to/site" --adapter cli

# For Remote Sites
claude mcp add wp-live node /absolute/path/to/wordpress-mcp/dist/index.js -- --adapter rest --url "https://your-site.com" --username "your_user" --password "xxxx xxxx xxxx xxxx"

C. Google Antigravity

Add to ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "wordpress": {
      "command": "node",
      "args": [
        "/absolute/path/to/wordpress-mcp/dist/index.js",
        "--adapter", "rest",
        "--url", "https://your-site.com",
        "--username", "your_user",
        "--password", "xxxx xxxx xxxx xxxx"
      ]
    }
  }
}

🎮 Interactive Web Playground

Need to verify tool responses or test connectivity before configuring your AI agent? Run the built-in visual tester:

npm run dashboard

Then visit http://localhost:3300 in your browser. You can execute tools with a single click, view raw JSON-RPC responses, switch sites, and toggle Safe Mode interactively.

🔒 Security Architecture

1. Safe Mode Enforcement:

   • Out of the box, wordpress-mcp is read-only.

   • Any attempt to invoke wp_create_post or wp_update_post returns a clear security error.

   • To permit write actions, pass --allow-write in your command args or set SAFE_MODE=false.

2. Dedicated Credentials:

   • Use WordPress Application Passwords that can be instantly revoked at any moment.

3. Audit Trail:

   • Pass --audit-log /path/to/audit.log to record every tool call with timestamps and arguments.

🤝 Contributing

Contributions, issues, and feature requests are welcome! Please read our Contributing Guide and Security Policy.

📄 License

This project is licensed under the MIT License.
Created with ❤️ by Amin Zahed (Ameeen).