npm package: @leonardobora/mcp-wordpress
Description: MCP server for WordPress REST API — manage pages, posts, shortcodes and Elementor content from Claude Code.
Author: Leonardo Bora
Latest version: 1.0.0

# 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

- **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

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

```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.

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:

```bash
npm test
```

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

## License

MIT