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

• 80 tools covering content CRUD, Gutenberg blocks, direct-sale ads, classic menus/widgets, settings, Blocksy page layout, patterns, revisions, taxonomies, media, shortcode surgery, site diagnostics, and cache
• Shortcode parser — reads, replaces, and inserts shortcodes without touching surrounding content
• Gutenberg-native — addresses blocks by path, hash, anchor, metadata name, or explicit query and prevents ambiguous edits
• 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, wp_whoami | Site information and authenticated-user capabilities | | wp_list_pages, wp_get_page, wp_create_page, wp_update_page, wp_delete_page | Page CRUD with pagination and concurrency guards | | wp_list_posts, wp_get_post, wp_create_post, wp_update_post, wp_delete_post | Post CRUD, taxonomy assignment, scheduling and featured media | | wp_list_categories, wp_create_category, wp_ensure_category, wp_update_category, wp_delete_category | Category management | | wp_list_tags, wp_create_tag, wp_ensure_tag, wp_update_tag, wp_delete_tag | Tag management | | wp_list_media, wp_get_media, wp_upload_media, wp_update_media, wp_delete_media, wp_set_featured_image | Media library and featured-image operations | | wp_blocks_list, wp_blocks_get, wp_blocks_find | Gutenberg outlines and safe block addressing | | wp_blocks_insert, wp_blocks_replace, wp_blocks_update, wp_blocks_delete, wp_blocks_move | Gutenberg mutations with structural diffs, hash guards, and normalization checks | | wp_list_sidebars, wp_list_widgets, wp_get_widget, wp_create_widget, wp_update_widget, wp_delete_widget, wp_move_widget | Classic widget management, exact ordering, and structured ad creatives (including full-width placements) | | wp_list_content_blocks, wp_get_content_block, wp_update_content_block | Existing Blocksy Content Block slots; creation is intentionally unavailable to prevent orphan blocks | | wp_list_revisions, wp_get_revision, wp_diff_revision, wp_restore_revision | Revision history and restore with an honest core REST fallback | | wp_list_menus, wp_get_menu, wp_create_menu, wp_update_menu, wp_delete_menu, wp_list_menu_locations, wp_assign_menu_location | Classic menus and theme-location assignment | | wp_list_menu_items, wp_get_menu_item, wp_create_menu_item, wp_update_menu_item, wp_delete_menu_item | Classic menu item CRUD and ordering | | wp_get_settings, wp_update_settings | Site settings and guarded static-front-page switching (manage_options) | | wp_set_blocksy_page_layout | Optional-companion control for a page-specific right, left, or absent Blocksy sidebar | | wp_list_synced_patterns, wp_get_synced_pattern, wp_create_synced_pattern, wp_update_synced_pattern, wp_delete_synced_pattern | Synced pattern CRUD | | wp_list_block_patterns, wp_get_block_pattern | Read-only core/theme/plugin registered patterns | | 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_elementor_get_shortcode_content, wp_elementor_update_shortcode_content | Reserved compatibility tools that currently fail explicitly; safe Elementor REST support is planned for v1.4 | | 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.

The news-portal recipe in src/portal/home.js generates canonical Gutenberg sections for breaking news, category grids, latest posts, popularity, and up to three sponsors, plus an ordered sidebar recipe. Its Docker integration test applies the recipe through the registered MCP tools and verifies the resulting public HTML. Popularity is explicit: comments mode is labelled “Em alta por comentários”; “Mais vistas” requires a real view-provider shortcode.

Elementor _elementor_data is protected post meta and cannot be safely read or written through the core posts REST controller. The compatibility tools therefore fail explicitly instead of reporting false success.

All supported mutations accept dry_run:true. Set WP_MCP_DRY_RUN=1 to force previews globally. Set WP_MCP_CONFIRM_DESTRUCTIVE=1 to require a matching dry-run immediately before any permanent (force:true) deletion.

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
• A page-scoped cache flush requires edit_post for that page; an explicit site-wide flush requires edit_pages

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) | | WP_MCP_DRY_RUN | No | Set to 1 to force every supported mutation into dry-run mode, regardless of per-call dry_run | | WP_MCP_CONFIRM_DESTRUCTIVE | No | Set to 1 to require a matching dry-run immediately before any permanent (force:true) deletion |

Testing

Run unit, type, lint, and offline MCP smoke checks:

npm test
npm run typecheck
npm run lint
npm run test:smoke

Run the isolated WordPress 6.8 + Blocksy integration suite with Docker:

npm run integration:up
WP_MCP_IT=1 npm run test:integration
npm run integration:down

The integration environment uses only project-scoped containers and named volumes. integration:down removes those test volumes.

What's New

Recent work brought the server from a single-file shortcode/Elementor tool to an 80-tool modular MCP server with a real WordPress test loop:

• Modularized tools with dry-run support — split the monolithic server into per-domain tool modules (src/tools/*.js) behind a shared registry (src/registry.js), and added opt-in dry_run previews plus the WP_MCP_DRY_RUN / WP_MCP_CONFIRM_DESTRUCTIVE env-var safeguards for destructive calls.
• Content CRUD and taxonomy tools — added full page/post create-update-delete and category/tag management, including idempotent wp_ensure_category/wp_ensure_tag.
• Media management tools — added the media library and featured-image tool set (wp_list_media, wp_upload_media, wp_update_media, wp_delete_media, wp_set_featured_image).
• Docker WordPress integration suite — added a project-scoped Docker Compose environment (test/integration/) that provisions a real WordPress 6.8 + Blocksy site and runs end-to-end tests against it (WP_MCP_IT=1 npm run test:integration), wired into CI.
• Expanded tool coverage to 80 tools — added Gutenberg block, revision, widget, menu, settings, pattern, and Blocksy layout tools, plus companion REST endpoints for scoped cache purges and revision restore.
• Gutenberg block and classic WordPress tools — added block parsing/addressing/transform helpers, shortcode helpers, ad-creative generation, and the news-portal recipe (src/portal/home.js) that assembles canonical Gutenberg sections for breaking news, category grids, latest posts, popularity, and sponsors.
• Full-width ad creative blocks — extended the structured ad-creative helper (src/blocks/ad.js) with a full_width option for edge-to-edge placements.

Acknowledgment

The expansion from a 14-tool server to the current 80-tool modular MCP server was authored by André Escocard (andreescocard) and merged in PR #1: tool registry, dry-run and destructive-operation safeguards, content/media/taxonomy tools, Gutenberg blocks, menus, widgets, revisions, patterns, settings, the Blocksy companion endpoints, the Docker WordPress integration suite, and CI/lint/typecheck coverage.

License

MIT