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