mcp-wordpress

MCP server for WordPress REST API. Lets Claude Code read, edit, and manage WordPress pages, posts, shortcodes, and media — all from the CLI.

Works with any WordPress site, any theme, any set of plugins.

Features

• 14 tools covering the full content lifecycle: list, read, edit, shortcode surgery, Elementor support, media, cache
• Shortcode parser — reads, replaces, and inserts shortcodes without touching surrounding content
• Elementor-aware — reads/writes _elementor_data directly when pages use Elementor widgets
• Cache flush — clears Elementor CSS, WP object cache, and popular cache plugins (W3TC, LiteSpeed, WP Super Cache, WP Fastest Cache)
• Zero config — just three env vars and you're connected

Quick Start

1. Install

npx @leonardobora/mcp-wordpress
# or clone and run locally:
git clone https://github.com/leonardobora/mcp-wordpress.git
cd mcp-wordpress && npm install

2. Create a WordPress Application Password

1. Log in to WordPress admin
2. Go to Users > Profile
3. Scroll to Application Passwords
4. Enter a name (e.g. "Claude Code") and click Add New Application Password
5. Copy the generated password (you won't see it again)

3. Register in your project

Add a .mcp.json to the root of your project:

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "@leonardobora/mcp-wordpress"],
      "env": {
        "WP_SITE_URL": "https://your-site.com",
        "WP_USERNAME": "your-username",
        "WP_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
      }
    }
  }
}

Or if running from a local clone:

{
  "mcpServers": {
    "wordpress": {
      "command": "node",
      "args": ["path/to/mcp-wordpress/src/server.js"],
      "env": {
        "WP_SITE_URL": "https://your-site.com",
        "WP_USERNAME": "your-username",
        "WP_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
      }
    }
  }
}

4. (Optional) Enable cache flush

Copy examples/mcp-wordpress-flush-cache.php to your WordPress wp-content/mu-plugins/ directory. This enables the wp_flush_cache tool.

If your site already has a custom cache flush endpoint, set the WP_FLUSH_ENDPOINT env var:

"env": {
  "WP_FLUSH_ENDPOINT": "my-plugin/v1/flush-cache"
}

Available Tools

| Tool | Description | |------|-------------| | wp_site_info | Get site name, URL, description | | wp_list_pages | List all pages (ID, title, slug, status) | | wp_list_posts | List all posts | | wp_get_page | Get full raw content of a page (by ID or slug) | | wp_get_post | Get full raw content of a post by ID | | wp_list_shortcodes | Parse and list all shortcodes in a page | | wp_update_page_content | Replace entire page content | | wp_update_post_content | Replace entire post content | | wp_replace_shortcode | Find and replace a specific shortcode in a page | | wp_insert_shortcode | Insert content before/after a shortcode | | wp_list_media | List media library items with URLs | | wp_elementor_get_shortcode_content | Read shortcodes from Elementor widget data | | wp_elementor_update_shortcode_content | Update shortcodes inside Elementor widgets | | wp_flush_cache | Flush WordPress + Elementor + plugin caches |

Usage Examples

Once registered, Claude Code can:

> List all pages on the site
> Show me the shortcodes on the Home page
> Replace the hero title on the About page to "Our Story"
> Insert a testimonials section after the feature cards on the Home page
> What images do we have in the media library?
> Flush the cache for page #275

How It Works

The server connects to the WordPress REST API using Basic Auth (Application Passwords). It exposes MCP tools that Claude Code can call to read and modify content.

For shortcode operations, the server includes a custom parser (shortcode-utils.js) that understands WordPress shortcode syntax — [tag attr="value"] and [tag]content[/tag] — enabling surgical find-and-replace without touching surrounding content.

For Elementor pages, the server reads _elementor_data post meta directly, walks the widget tree, and can extract or update shortcode widgets without going through the Elementor editor.

Security

• Never commit .env or Application Passwords to version control
• Application Passwords can be revoked at any time from WordPress admin
• The server uses Basic Auth over HTTPS — ensure your site has SSL
• Consider creating a dedicated WordPress user with Editor role (not Administrator) for tighter permissions
• The cache flush endpoint requires edit_pages capability

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | WP_SITE_URL | Yes | WordPress site URL (e.g. https://your-site.com) | | WP_USERNAME | Yes | WordPress username | | WP_APP_PASSWORD | Yes | Application Password | | WP_FLUSH_ENDPOINT | No | Custom REST endpoint for cache flush (default: wp-mcp/v1/flush-cache) |

Testing

Set your env vars and run:

npm test

This connects to the MCP server, lists available tools, and runs basic smoke tests against your WordPress site.

License

MIT