---
title: "Block MCP — the WordPress MCP that edits one block at a time"
date: 2026-05-18
author: "Casey Burridge"
link: "https://www.gravitykit.com/wordpress-block-mcp/"
---

# Finally, a WordPress MCP that doesn’t mangle your blocks

Block MCP exposes Gutenberg as a structured, addressable block tree. AI agents can change a single heading without rewriting the page, chain edits across turns, and roll back any write with one call. Free and open source.

[View Block MCP on GitHub](https://github.com/GravityKit/block-mcp)![](https://www.gravitykit.com/wp-content/uploads/2026/05/block-mcp.jpg)---

## Most WordPress MCPs don’t care about block structure…which breaks your pages!

The standard WordPress REST API was built for posting, not editing. When an AI agent uses it to change one heading, it has to read the full HTML, parse it, mutate it, and write the whole post back.

That round trip is where things break:

- `` block markers get stripped, so blocks reopen with "this block contains unexpected or invalid content" warnings.
- Every multi-step edit re-sends the entire page body, which is slow and expensive.
- Block attributes drift out of sync with rendered HTML: the comment marker still says `level: 2`, the inner tag is now ``, and the editor flags the block as broken.
- A simple typo fix becomes a full revision; six small edits leave six revisions in your history.

Automattic ships [vip-block-data-api](https://github.com/Automattic/vip-block-data-api) for the same underlying reason: raw `post_content` strings are the wrong surface when something other than wp-admin needs to consume structured block data. Their plugin solves the headless-CMS case (read-only, frontend rendering). Block MCP solves the AI-editing case — the write side of the same problem.

| Dimension | vip-block-data-api | Block MCP |

|---|---|---|
| Direction | Read-only | Full CRUD + mutation engine |
| Consumer | React/Vue frontends, mobile apps | AI agents |
| Surface | REST + GraphQL (WPGraphQL) | REST + MCP server (stdio) |
| Editing primitives | None | 9 path-based ops, atomic batch (≤50), refs, revisions, ETag |
| Attribute extraction | `block.json` source selectors via DomCrawler | Raw `parse_blocks()` |
| Safety | n/a (read-only) | wp\_kses, depth cap, ref locking, rate limits, tier policy, SSRF guard |
| Integrations | WPGraphQL | Yoast SEO |
| Auth default | Public read (filterable) | Requires `edit_posts` capability |
`post_content`
![This is fine — broken WordPress blocks after AI editing](https://www.gravitykit.com/wp-content/uploads/2026/05/block-meme-1.jpg)

## A WordPress MCP built around the block tree

Block MCP is two pieces: a WordPress plugin that exposes a structured block tree at `gk-block-api/v1`, and a TypeScript MCP server that hands those tools to your agent.

Agents read the page once as JSON. They edit by block, by reference, or by path. They write through endpoints that know what blocks are.

### Three things that change everything

#### Stable refs, not indexes

Every block carries a persistent `gk_ref` UUID. Agents can fetch a page once, capture the refs they care about, and chain inserts, deletes, and updates across turns without re-reading. Sibling shifts don't invalidate addresses. No other WordPress MCP does this.

#### Atomic batch edits

`update_blocks` applies up to 50 independent updates in a single revision. All-or-nothing validation: a stale ref or out-of-range index aborts the whole batch before anything hits disk. Six typo fixes become one revision, not six.

#### Server-side tier policy

Decide which block types agents are allowed to write before the request hits disk. Legacy blocks get rejected outright with a suggested replacement. Avoid-tier blocks return warnings. Your block discipline survives contact with the agent.

## Three components, one round trip

![Diagram showing the three components of an MCP integration: an AI agent (your app) on the left, an MCP server (your machine) in the middle, and a WordPress plugin (your site) on the right. The AI agent connects to the MCP server via stdio, and the MCP server connects to the WordPress plugin via HTTPS. A label below reads "Three components, one round trip."](https://www.gravitykit.com/wp-content/uploads/2026/05/block-mcp-round-trip-1024x475.jpg)The plugin handles parsing, serialization, safety checks, preference scoring, rate limiting, and revisions. Authentication runs through a normal WordPress Application Password—no special privileges, no direct database access.

### What the agent gets

- **Read tools:** full block tree, page summary, outline mode, text search.
- **Write tools:** single-block updates, atomic batches (up to 50 in one revision), full-page rewrites, one-call rollback.
- **Discovery:** block types with preference tiers, patterns, site-wide block usage, URL-to-ID resolution.
- **Yoast SEO:** titles, descriptions, focus keywords, schema, Open Graph, Twitter cards. Available the moment Yoast SEO is active.

For the full tool reference, see the [README](https://github.com/GravityKit/block-mcp/blob/main/README.md).

## We put Claude in front of three WordPress MCPs and asked it to change a heading

Same instruction across the board: *change the H2 heading "Code samples" to H3.* Three MCPs, three Claude models, three trials each. 27 runs total. We re-opened each page in the block editor and inspected it.

| Model | Block MCP | AI Engine Pro | InstaWP/mcp-wp |
|---|---|---|---|
| Haiku | 🟢 3 / 3 · 10s avg | 🟡 2 / 3 · 44s avg | 🔴 0 / 3 · 20s avg |
| Sonnet | 🟢 3 / 3 · 9s avg | 🟢 3 / 3 · 14s avg | 🔴 0 / 3 · 36s avg |
| Opus | 🟢 3 / 3 · 9s avg | 🟢 3 / 3 · 13s avg | 🔴 2 / 3 · 38s avg |
| **Total** | **9 / 9** | **8 / 9** | **2 / 9** |

### Three takeaways

- **Block MCP works on the cheapest model and finishes fastest.** Haiku passes every trial in 10 seconds because the API is shaped exactly like the task.
- **InstaWP's wp/v2 wrapper fails 7 out of 9 times.** The agent reports success and the heading text changes, but the round trip strips block markers and the page reopens with editor warnings on most blocks.
- **AI Engine Pro is competitive on Sonnet and Opus** but stumbles on Haiku, where rendered HTML and declared attributes drift out of sync.

We also ran five harder structural scenarios — moving a block, inserting a paragraph inside a `core/group`, adding and deleting table rows and columns. Block MCP went 5 for 5 in 13 seconds and two tool calls per scenario on average. InstaWP failed all five.

## Built for the people who actually edit WordPress sites

Block MCP is useful anywhere you want an agent to make precise, surgical edits to WordPress content. A few of the workflows it shows up in:

### Agencies and consultants

Ship client work faster without giving up control over what ends up in `post_content`. Set the tier policy once, and every agent your team runs against that site stays inside the block library you've approved. Stale refs, broken markup, and surprise revisions stop being your problem.

### Developers and AI tooling builders

Build agents that edit pages reliably across multi-turn loops. Refs are stable, writes are revisioned, mutations are atomic, and concurrency is guarded by ETag/If-Match. The repo includes a TypeScript SDK, a stdio server, and an end-to-end smoke script for live validation.

### Teams running content workflows

Editorial assistants, SEO updates, batch metadata changes, programmatic launch posts. Anywhere a human used to copy-paste through the block editor, an agent can now do the same work with one revision per logical change and a clean rollback path.

## Get set up in 3 simple steps

- **Install the WordPress plugin.** Download the latest release ZIP from GitHub and upload it via Plugins → Add New, or use WP-CLI: `wp plugin install  --activate`.
- **Create an Application Password.** In WordPress admin: Users → Profile → Application Passwords. The user needs `edit_posts` for any post you want to read or write.
- **Register the MCP server with your client.** Clone the repo, run `npm install`, then add the server to your MCP client config with your WordPress URL, username, and Application Password.

### Example MCP client config

```
{
  "mcpServers": {
    "block-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/block-mcp/dist/index.cjs"],
      "env": {
        "WORDPRESS_URL": "https://example.com",
        "WORDPRESS_USER": "your-wp-username",
        "WORDPRESS_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
      }
    }
  }
}
```

Full setup instructions are in [the README](https://github.com/GravityKit/block-mcp/blob/main/README.md).

## If you would like to learn more…

We’re working on more content showing how to use the Block MCP. If you'd like to be notified when it's published, sign up for our newsletter!

##### Helpful tips right in your inbox

We’re constantly improving GravityKit. Fill out your email below and we’ll notify you anytime major updates drop.