# mcp-wordpress

MCP server for WordPress REST API. Lets [Claude Code](https://claude.ai/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

```bash
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:

```json
{
  "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:

```json
{
  "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:

```json
"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:

```text
> 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](https://developer.wordpress.org/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:

```bash
npm test
npm run typecheck
npm run lint
npm run test:smoke
```

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

```bash
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](https://github.com/andreescocard)) and
merged in [PR #1](https://github.com/leonardobora/mcp-wordpress/pull/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