WordPress Block MCP

What matters is whether the page is correct after the agent finishes. So we put Claude in front of each MCP, typed a real instruction —"change the H2 heading 'Code samples' to H3"— then re-opened the page and inspected it.

InstaWP's wp/v2 wrapper fails 7 out of 9 times — even Opus only gets it right 2/3.When the agent reports success, it's technically right that the heading text changed. But the whole-page round-trip throughupdate_pagestrips every<!-- wp: -->block marker. Reopen the page in the block editor and you'll see "This block contains unexpected or invalid content" warnings on most blocks. The standard REST API isn't broken — it does exactly what it's documented to do — but its data shape lets the AI corrupt content without realizing it.

AI Engine Pro is competitive with Sonnet and Opus but stumbles on Haiku.Itswp_alter_posttool is block-aware (the post markup stays valid), but on the failed Haiku trials the rendered HTML and the block's declared attributes drift out of sync — e.g., the comment marker still sayslevel: 2while the inner tag is<h3>. The block editor flags that as broken too. Sonnet and Opus retry until consistent (2–3 tool calls); Haiku sometimes gives up after declaring success.

Now try the structural ops agents actually need

A single heading-level change is the easy case. The interesting work is when an agent has to move a block, drop a paragraph inside an existing container, modify a table, or delete a block — the kind of multi-step structural editing real content workflows demand.

Five harder scenarios. Same matrix: three MCPs × Claude Haiku.

Block MCP averages 13 seconds and two tool calls per scenario.The agent reads the page once, finds the target block by ref or path, calls one mutation, done.

AI Engine Pro keeps the page intact and finishes correctly,about 2× slower. Itswp_alter_posttool asks the agent to supply both the block-comment markup and the rendered HTML, so most scenarios spend an extra round-trip generating the right shape.

InstaWP/mcp-wp fails every scenario with a "structural fail":the agent (Haiku, givenupdate_page) writes the page back as plain HTML —<h1>...</h1><p>...</p><ol>...— with no<!-- wp: -->block markers. WordPress accepts the save,parse_blocks()collapses the entire page into one freeform chunk, and every distinctive block on the page disappears as a structured entity. The agent thinks it succeeded; the page is broken in the block editor on reopen. That's the penalty of wrapping the standard wp/v2 REST surface and trusting the agent to reconstruct block markup by hand.

Block MCP(this project) — Operates one layer below: inside a single post's block tree. Path- and ref-based addressing, auto-transforms that keep attributes and innerHTML in sync server-side, preference-tier enforcement, per-block revisions. None of those exist in the other three. Reach for it when an agent needs to editblocks— change a heading level, swap a column layout, insert a CTA after the third paragraph — without rewriting the surrounding content. 9 of 9 in the bench, perfect across all three Claude models, including the cheapest.

- Full block tree as structured JSON: paths, names, attributes, refs,text_previewof each block's content
- Page summary in one call: block type counts, headings with paths, section markers, max nesting depth
- Outline mode for fast page structure inspection
- Search blocks by text or block name
- Render mode expands shortcodes, resolves synced patterns, marks dynamic blocks

- update_block— flat-index OR ref
- update_blocks— atomic N-update batch in ONE revision; all-or-nothing validation, max 50 items, counts as one write against the rate limit
- delete_block— top-level counter OR ref
- insert_blocks— anchor onafter_top_level/before_top_levelORafter_ref/before_ref
- edit_block_tree— 9 path-based or ref-based structural ops:

- update-attrs,update-html,replace-block,remove-block
- wrap-in-group,unwrap-group,insert-child,duplicate,move

- Auto-transform keeps innerHTML in sync when attributes change (heading level, list ordered, group tagName, button URL, image src, spacer height, etc.)
- Static block guards warn when an attribute change may leave rendered markup stale
- Configurable preference tiers: legacy blocks rejected on insert, avoid-tier blocks return warnings with suggested replacements
- Per-post rate limiting (10 writes/min, 2 full rewrites/min)
- Every write creates a WordPress revision;revert_to_revisionundoes any edit

- List block types filtered by namespace, category, or preference tier
- Browse patterns (synced + registered) scored by recency, reference count, and legacy content
- Site-wide block/pattern usage analytics (cached)
- Resolve any URL or slug to its post ID, type, and edit link

AI Agent ←stdio→ MCP server (your machine) ←HTTPS→ WordPress plugin (your site)

WordPress plugin(wordpress-plugin/gk-block-mcp/) — REST API atgk-block-api/v1. Handles block parsing, serialization, safety checks, preference scoring, rate limiting, revisions. Works with any post type that stores Gutenberg blocks inpost_content.

MCP server(src/) — TypeScript stdio server that exposes the REST API as MCP tools. Authenticates as a normal WordPress user via Application Password. No special privileges, no direct DB access from the MCP side.

Then in WordPress:Plugins → Add New → Upload Pluginand pick the ZIP.

Or copywordpress-plugin/gk-block-mcp/to your site'swp-content/plugins/and activate manually. Or via WP-CLI:

wp plugin install https://github.com/GravityKit/block-mcp/releases/download/latest/gk-block-mcp.zip --activate

The fastest path provisions everything for you — a dedicatedblock-mcpservice account, a minimal-capability role, and an Application Password — from inside WordPress. Go toSettings → Block MCP → Connectand pick your client.

Claude Desktop (one-click).Download the generated.mcpbfile and open it; Claude Desktop installs the server and stores the credential in your OS keychain. The.mcpbis self-contained — it bundles the server, so there's nothing else to install.

Cursor, Claude Code, ChatGPT Desktop (browser approve).Run the connector and clickApprovein the browser that opens:

npx -y @gravitykit/block-mcp connect --site https://example.com

It writes your client's MCP config for you (owner-only, mode0600), so the site-wide password never lands in your shell history or a hand-edited file. Add--client cursor|claude-code|claude-desktop|printto target a specific client. Each site you connect gets its own server entry, so one assistant can point at several sites.

Runtime:the common path runs the server withnpx -y @gravitykit/block-mcp— nothing to clone or build. The Claude Desktop.mcpbembeds the same bundle.

Prefer to wire it up by hand? Create an Application Password and register the server yourself.

In WordPress admin:Users → Profile → Application Passwords. Or via CLI:

wp user application-password create <username> "Block MCP" --porcelain

Read endpoints require theedit_postscapability; write endpoints requireedit_poston the specific post being changed. Then build and register the server:

git clone https://github.com/GravityKit/block-mcp cd block-mcp npm install # auto-builds dist/index.cjs via the prepare script

Register the server in your MCP client. Example for Claude Code's~/.claude.json:

list_templates/get_templateare read-only tools for browsing a block theme's templates (page layouts likesingle,archive) and template parts (reusable regions likeheader,footer), the same content the Site Editor's template list shows.

Each row'swp_idtells you whether a database override currently shadows the theme file:nullmeans the id resolves to the theme file itself; a number means a customization exists and that post ID is the override. On a classic (non-block) theme,list_templatesreturns an empty list with anoteexplaining why, rather than an error.

Templates are index-addressed only.get_template'sblocksfield is formatted likeget_page_blocks. Whether the per-block write tools (update_block,edit_block_treeby ref) apply depends on thewp_id: a template that still resolves to the theme file (wp_id: null) is not writable by them, while a template with a database override (a numericwp_id) is an ordinary post they edit like any other. Useupdate_template(see Editing templates below) to materialize the override for a theme-file-only template.

update_template/reset_templatewrite to templates. Both are off by default. Enable"Let the assistant edit theme templates and template parts"under Settings → Block MCP first, or every call returns a 403 with an actionable message. Turning the toggle on grants the Block MCP agent account a dedicatedgk_block_mcp_edit_templatescapability (nothing else it can do changes); a human's own "self" connection can edit templates too, since it already carriesedit_theme_options.

- update_templatereplaces a template's entire content: whole-template replacement, likerewrite_post_blocks, not a per-block edit. Provide exactly one ofcontent(raw markup) orblocks(structured; validated against the block registry and preference tiers, same as any other structured-block write). If the id currently resolves to the theme file, a database override is created automatically (override_created: true); the theme file itself is never touched. Writing again reuses the same override.
- reset_templatedeletes the override, reverting the id back to the theme file. Appearance → Editor → Reset does the same thing from the WordPress admin.

Once an override exists, itswp_idis a normal post ID —update_block,get_page_blocks, and the rest of the per-block tool surface work against it like any other post.

Every block in aget_page_blocksresponse includes areffield: