@abidingbear/wp-mcp

A WordPress MCP (Model Context Protocol) server for Claude Code with WP-CLI integration and GeneratePress theme support.

Features

• Core WordPress Tools: Manage posts, pages, options, and site settings
• GeneratePress Integration: Full control over GP theme settings, colors, typography, and layout
• Multi-site Support: Configure and manage multiple WordPress installations
• WP-CLI Powered: Uses WP-CLI for reliable WordPress operations

Requirements

• Node.js 20+
• WP-CLI installed and accessible
• WordPress site(s) with shell access

Installation

For Claude Code Users

Add to your project's .mcp.json:

{
  "mcpServers": {
    "wp-mcp": {
      "command": "npx",
      "args": ["-y", "@abidingbear/wp-mcp"]
    }
  }
}

Configuration

Create a sites configuration file at ~/.wp-mcp.json:

{
  "sites": {
    "my-site": {
      "path": "/path/to/wordpress/installation",
      "theme": "generatepress",
      "description": "My WordPress site"
    }
  }
}

Or use the environment variable WP_MCP_SITES to specify a custom config path.

Config File Locations

The server checks these locations in order:

1. $WP_MCP_SITES environment variable
2. ~/.config/wp-mcp/sites.json
3. ~/.wp-mcp.json

Available Tools

Core Tools

| Tool | Description | |------|-------------| | wp_list_posts | List WordPress posts with filters | | wp_get_post | Get a single post by ID | | wp_create_post | Create a new post or page | | wp_create_post_with_blocks | Create post with Gutenberg blocks | | wp_update_post | Update an existing post | | wp_delete_post | Delete a post (trash or permanent) | | wp_get_option | Get a WordPress option value | | wp_set_option | Set a WordPress option value | | wp_patch_option | Update a key within a serialized option | | wp_list_options | List options matching a pattern | | wp_get_theme_mods | Get theme modification settings | | wp_set_theme_mod | Set a theme modification value | | wp_list_sites | List all configured sites | | wp_site_info | Get WordPress site information | | wp_list_themes | List installed themes | | wp_list_plugins | List installed plugins | | wp_flush_cache | Flush object cache and rewrite rules | | wp_search_replace | Search and replace in database | | wp_db_export | Export database to SQL file |

GeneratePress Tools

| Tool | Description | |------|-------------| | gp_get_settings | Get all GeneratePress theme settings | | gp_get_colors | Get global color palette | | gp_set_colors | Set global color palette | | gp_set_setting | Update a single GP setting | | gp_get_typography | Get typography settings (GP Premium) | | gp_get_layout | Get layout settings | | gp_set_container_width | Set container width | | gp_get_modules | Get GP Premium module status | | gp_regenerate_css | Regenerate dynamic CSS |

Auto-Detection

When running in a WordPress directory (or any subdirectory), the server automatically detects the WordPress installation by looking for wp-config.php. No configuration file is needed for local development.

The auto-detected site is available as local (or any site ID if it's the only configured site).

Usage Examples

List Posts

Use the wp_list_posts tool with site "local" to get recent posts

Update GeneratePress Colors

Use gp_set_colors to update the color palette for site "local"

Get Site Info

Use wp_site_info to get details about site "local"

Security

This package implements multiple layers of security to protect against command injection and other attacks:

Command Allowlist

Only specific WP-CLI commands are allowed:

• cache, core, db, option, plugin, post, rewrite, search-replace, theme

All other commands are rejected.

Input Validation

All user inputs are validated before use:

• Site IDs: Alphanumeric with hyphens/underscores only
• Option names: WordPress-safe characters only (max 191 chars)
• Post types/statuses: Validated against known WordPress values
• Colors: Must be valid hex format (#RGB, #RRGGBB, or #RRGGBBAA)
• File paths: Sanitized and validated for WordPress installations
• Search strings: Shell metacharacters rejected

Safe Shell Escaping

All values passed to shell commands use shell-quote for proper escaping, preventing command injection attacks.

Path Traversal Protection

• Paths are resolved to absolute paths
• Symlinks are validated
• WordPress installation is verified before operations
• Control characters and null bytes are rejected

Error Sanitization

Error messages are sanitized to avoid exposing internal system paths.

Troubleshooting

WP-CLI Not Found

Ensure WP-CLI is installed and available in your PATH:

wp --info

If using Local by Flywheel, open the site shell first or add Local's WP-CLI to your PATH.

Auto-Detection Not Working

Create a manual configuration at ~/.wp-mcp.json:

{
  "sites": {
    "local": {
      "path": "/path/to/your/wordpress"
    }
  }
}

License

MIT