wp-ops-mcp

An MCP server that lets an AI assistant read and edit WordPress sites over the REST API - including Divi 4 (shortcode-based), Divi 5 (block-based) and Gutenberg page content.

Works with any MCP client: Claude Code, Claude Desktop, Cursor, OpenCode.

45 tools · 1014 tests · HTTPS only, no SSH

Why this is interesting

Letting an LLM edit a page builder's content is mostly a safety problem. Divi 4 stores layouts as deeply nested shortcodes and Divi 5 as block comments; both are easy to parse approximately and very easy to corrupt. This server is built around not corrupting them.

The round-trip gate. Content is parsed to a tree and re-serialized before any edit is attempted. If the output is not byte-identical to the input, the tool refuses the page entirely. The parser is not trusted to be complete - it is only trusted to be honest about what it fully understands.

Edits never touch the live page. wp_edit_page duplicates the page to a draft, edits the draft, and verifies by reading back. A separate wp_publish_swap promotes it, and WordPress keeps a revision. A failed edit leaves the live page untouched.

Writes are preview-first. Every mutating tool defaults to dry_run=true and returns what would change. Production sites additionally require an explicit allow_prod=true.

Theme file writes route through WordPress core. wp_edit_theme_plugin_file() loopback-requests the site after writing and restores the file if the site fatals. This was verified by deliberately writing broken PHP to a live staging site: the tool errored, the file reverted byte-identically, and the site stayed up.

What it can do

Design notes worth reading

• A page that cannot be round-tripped is refused, not "best-efforted". A fleet scan of 125 real pages found 120 with no builder markup at all - those parse to a single text node, so structural ops correctly find nothing to target rather than guessing.

• The site-side plugin is deliberately tiny (~350 lines, 7 routes, every one capability-gated). Core REST does the heavy lifting; the plugin only adds what core cannot do - draft duplication, builder/SEO meta, ACF, options, cache purge, theme files.

• Two independent verification nets on writes: the plugin reports which keys it applied and the value is re-read from the site. A partial apply is an error, not a silent success.

• Environment is explicit, not guessed. Deriving "is this production?" from the install name misread real staging installs, so an explicit value always wins.

Setup

git clone https://github.com/<you>/wp-ops-mcp && cd wp-ops-mcp
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest -q

1. Zip wp_ops_mcp/plugin/wp-ops-connect/ and install it on the target site.

2. Create an administrator user there and generate an Application Password (administrator is required for unfiltered_html, or WordPress strips iframes and inline styles from content you write).

3. Copy data/wp_ops_mcp/credentials.example.json to credentials.json and fill it in.

4. Register the server:

claude mcp add wp-ops \
  --env WPOPS_TRANSPORT=rest \
  --env WPOPS_CREDENTIALS=/abs/path/to/data/wp_ops_mcp/credentials.json \
  -- python -m wp_ops_mcp.server

Docker: docker build -t wp-ops-mcp . && docker run --rm -i -v /abs/creds:/creds:ro wp-ops-mcp

Configuration

Known limits

• Classic (non-builder) pages are append-only - they round-trip safely but expose no addressable elements, so only insert operations apply.

• Theme files cannot be created, only edited - core's self-reverting editor only handles files a theme already registers.

• Rank Math noindex writes the whole robots array, so clearing it drops any nofollow/noarchive on that page.

• No plugin/theme updates, cache purge, or snapshot/rollback yet. Cache purge is the most useful missing piece: a correct write can look like a failure while a host serves a cached page.

Tests

pytest -q - 1014 pass. Two round-trip regression tests skip because their fixtures are real site content and are not distributed.

Unit tests do not catch REST contract drift or PHP errors; anything touching the site-side plugin needs a live staging test. See CONTRIBUTING.md.

Licence

MIT.