WordPress MCP Server (using PHP SDK)

A professional WordPress MCP (Model Context Protocol) server that enables AI assistants like Claude to interact with your WordPress site through a standardized protocol.

What is this?

This server exposes your WordPress content, taxonomies, and site information through MCP tools, allowing AI assistants to:

• List, read, create, update, and delete WordPress content (posts, pages, custom post types)
• Manage taxonomies (categories, tags, custom taxonomies) and terms
• Discover content types and taxonomies
• Search content by URL or slug

Features

✨ 17 WordPress Tools

• Content Management: list_content, get_content, create_content, update_content, delete_content
• Content Discovery: discover_content_types, get_content_by_slug, find_content_by_url
• Taxonomy Management: list_terms, get_term, create_term, update_term, delete_term
• Taxonomy Discovery: discover_taxonomies, get_taxonomy
• Term Assignment: assign_terms_to_content, get_content_terms

🔒 Secure & Production Ready

• Built with official PHP MCP SDK
• Comprehensive validation using Respect/Validation
• Proper error handling and logging
• 110+ passing unit tests

🚀 Easy Integration

• HTTP transport via StreamableHTTP (no complicated setup)
• Works with Claude Desktop via mcp-remote
• Simple installation in WordPress root

Installation

Step 1: Install in WordPress

1. Download this repository
2. Place the entire directory in your WordPress root folder (where wp-config.php is located)
3. Rename the directory to something simple like mcp-server

Your directory structure should look like:

/your-wordpress-site/
├── wp-admin/
├── wp-content/
├── wp-includes/
├── wp-config.php
├── mcp-server/          ← This directory
│   ├── index.php
│   ├── vendor/
│   └── ...

Step 2: Install Dependencies

Open terminal in the mcp-server directory and run:

composer install --no-dev

Step 3: Configure WordPress Path

The MCP server needs to know where your WordPress installation is located.

1. Copy the configuration template:

   cp config.example.php config.php

2. Edit config.php and set the wordpress_path to your WordPress installation:

   If MCP server is in WordPress root subdirectory (recommended):

   'wordpress_path' => '../wp-load.php',

   If WordPress is in a subdirectory (development):

   'wordpress_path' => 'wp/wp-load.php',

   Using absolute path:

   // Linux/macOS
   'wordpress_path' => '/var/www/html/wp-load.php',
   
   // Windows (use forward slashes)
   'wordpress_path' => 'C:/xampp/htdocs/mysite/wp-load.php',

Important: The config.php file is git-ignored and specific to your installation. Never commit it to version control.

Step 3.5: (Optional) Enable Safe Mode

Safe mode prevents destructive delete operations, providing an extra layer of protection for your WordPress content.

What Safe Mode Does:

• Blocks: delete_content and delete_term operations
• Allows: All read operations and write operations (create, update)

When to Enable Safe Mode:

• Production environments where accidental deletions must be prevented
• Shared environments with multiple users
• Read-mostly or limited-write access scenarios
• Testing and development where data preservation is important

To Enable Safe Mode:

Edit config.php and set:

'safe_mode' => true,

When a delete operation is attempted with safe mode enabled, the tool will return an error message:

Operation blocked: Safe mode is enabled. Deleting content is not allowed.

Default: Safe mode is OFF (false), allowing all operations including deletions.

Step 4: Verify Access

Make sure your web server (Apache/Nginx) can access the mcp-server directory.

Access URL: The server will be accessible at: https://your-site.com/mcp-server/index.php

Step 5: Test the Server

Visit https://your-site.com/mcp-server/index.php in your browser. You should see a JSON response indicating the MCP server is running.

Claude Desktop Integration

This server supports two connection methods:

Option 1: HTTP Transport (Recommended for Remote Sites)

Use this method when connecting to a remote WordPress site via HTTP/HTTPS.

Install mcp-remote (optional, Claude Desktop can do this itself):

npm install -g mcp-remote

Configure Claude Desktop:

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-site.com/mcp-server/index.php"
      ]
    }
  }
}

Note: Replace https://your-site.com/mcp-server/index.php with your actual URL.

For local development (HTTP without SSL):

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://your-local-site.test/mcp-server/index.php",
        "--allow-http"
      ]
    }
  }
}

Option 2: Stdio Transport (Recommended for Local Sites)

Use this method when running WordPress locally on the same machine as Claude Desktop. This is faster and doesn't require HTTP.

Configure Claude Desktop:

{
  "mcpServers": {
    "wordpress": {
      "command": "php",
      "args": [
        "/absolute/path/to/your-wordpress-site/mcp-server/server.php"
      ]
    }
  }
}

Example for macOS/Linux:

{
  "mcpServers": {
    "wordpress": {
      "command": "php",
      "args": [
        "/Users/yourname/Sites/mywordpress/mcp-server/server.php"
      ]
    }
  }
}

Example for Windows:

{
  "mcpServers": {
    "wordpress": {
      "command": "php",
      "args": [
        "C:\\xampp\\htdocs\\mywordpress\\mcp-server\\server.php"
      ]
    }
  }
}

Note:

• Make sure php is in your system PATH
• Use the absolute path to server.php
• Stdio transport doesn't require a web server to be running

Restart Claude Desktop

After adding the configuration, restart Claude Desktop completely (quit and reopen).

Using with Claude

Once configured, you can ask Claude things like:

• "List all my blog posts"
• "Create a new draft post titled 'Hello World'"
• "What categories do I have?"
• "Update post ID 5 to published status"
• "Find the post with URL https://mysite.com/my-post"
• "Show me all pages on my site"

Claude will use the MCP tools to interact with your WordPress site automatically!

Example Prompts

Content Management:

• "List my latest 5 published posts"
• "Create a new post titled 'My New Article' with some sample content"
• "Update the post titled 'About Us' to change its status to draft"
• "Show me all draft posts"

Taxonomy Management:

• "List all categories"
• "Create a new category called 'Technology'"
• "What tags exist on my site?"
• "Assign the 'Technology' category to post ID 10"

Discovery:

• "What content types does my WordPress site have?"
• "What taxonomies are registered?"
• "Find the post at URL https://mysite.com/2024/hello-world"

Troubleshooting

Server not responding

1. Check URL: Make sure the URL in your Claude config is correct and accessible
2. Clear sessions: Delete the sessions/ directory contents: rm -rf mcp-server/sessions/*
3. Check permissions: Ensure the web server can read/write to the sessions/ directory

chmod -R 755 mcp-server/
chmod -R 777 mcp-server/sessions/

"Connection refused" or "Cannot connect"

1. Verify the server is running: Visit the URL in your browser
2. Check firewall: Ensure your firewall allows access to the web server
3. Check SSL: For HTTPS sites, ensure your SSL certificate is valid

Tools not working

1. Check WordPress path: Verify that config.php has the correct path to your WordPress installation:

   'wordpress_path' => '../wp-load.php',  // Update this path

2. Clear sessions:

   rm -rf sessions/*

3. Check error logs: Look at php-errors.log in the mcp-server directory

Claude can't see the tools

1. Restart Claude Desktop completely (quit and reopen, don't just close the window)
2. Check config syntax: Ensure your claude_desktop_config.json is valid JSON
3. Check logs: Claude Desktop logs are at:
   • macOS: ~/Library/Logs/Claude/
   • Windows: %APPDATA%\Claude\logs\

Testing the Server

You can test the MCP server directly using the MCP inspector:

# Install inspector
npm install -g @modelcontextprotocol/inspector

# List all tools
npx @modelcontextprotocol/inspector --cli https://your-site.com/mcp-server/index.php --transport http --method tools/list

# Test a tool
npx @modelcontextprotocol/inspector --cli https://your-site.com/mcp-server/index.php --transport http --method tools/call --tool-name discover_content_types

Security Considerations

⚠️ Important Security Notes:

1. Authentication: This server does NOT include authentication. Make sure to:

   • Use HTTPS (SSL/TLS) for all connections
   • Restrict access using web server configuration (IP whitelist, Basic Auth, etc.)
   • Consider implementing WordPress authentication in production

2. Access Control: The server has full access to your WordPress database through WordPress functions. Only expose it to trusted clients.

3. Firewall: Consider using a firewall or VPN to restrict access to trusted IPs only. You can configure IP restrictions in your web server configuration (Apache VirtualHost or Nginx server block).

Development

For developers who want to extend this server:

• See CLAUDE.md for development documentation
• Run tests: composer test
• Run static analysis: composer analyse
• Inspector tests: ./tests/inspector-tests.sh

Requirements

• PHP 8.2 or higher
• WordPress 5.0 or higher
• Composer
• Node.js and npm (for mcp-remote)

Support

For issues, questions, or contributions, please visit the project repository.

License

This project is licensed under the MIT License.