Get the plugin
WP MCP/Integrations/Page builders

Page builders integration

Gutenberg AI agent tool reference

Gutenberg is the block editor that ships with WordPress. WP MCP gives your AI agent surgical control of it: read a post's parsed block tree, inspect block schemas, then insert, update, move, duplicate, or remove blocks by index path, and drop in registered patterns. It operates on the real block document, not string replacement, so everything stays native and editable. This is a free-tier integration.

parse-blocksadd-blockupdate-blockinsert-pattern

In practice

How Gutenberg work goes with an agent.

A Gutenberg post is a single string of HTML comments in post_content, and one stray character can break a block. WP MCP never edits that string directly. It parses the content into a block tree, hands back a sha256 content_hash, and every edit must send that hash back, so a change made in the meantime is caught. Blocks are addressed by an index path such as [1,0], and only the targeted block is rewritten. The other blocks come out byte for byte unchanged.

Show me the block structure of the Services page.

Runs parse-blocks with the post id, which returns the tree with an index path per block, plus the content_hash needed for edits. Read only. get-block-type and list-block-types show what attributes each block accepts.

Add a quote block after the second paragraph.

Runs add-block with the block markup, a path and the expected_hash. The post is snapshotted first, and the stored content is re-read afterwards. If it differs from what was serialized, the write is rolled back automatically.

Swap the third block with the fourth, then duplicate the call to action.

Runs move-block with from_path and to_index, then duplicate-block on the call to action. Each call needs a fresh hash from the previous result, and each is its own snapshotted operation.

Convert this pasted HTML into blocks and drop in the pricing pattern below it.

Runs convert-html-to-blocks, which only returns markup and writes nothing, then add-block or update-blocks to save it. insert-pattern then splices a registered pattern in at a path, with the same hash check and snapshot.

What your AI can do

Real Gutenberg operations, every write reversible.

  • Read a post's block tree with an index path per block
  • Insert, update, move, duplicate, and remove blocks precisely
  • Drop in registered block patterns
  • Inspect block type schemas before editing
  • Build custom Gutenberg blocks from a data spec (Pro; no code generation, no eval)
  • Undo any block edit, per change or per session

Example prompts

Example Gutenberg prompts.

Turn the last three paragraphs on /about into a two-column layout with a pull quote.

Insert the FAQ pattern above the footer on every Services page.

Replace the old pricing table block with the new three-tier pattern.

Under the hood

The Gutenberg calls, under the hood.

wpmcp, gutenberg

parse-blocks({ id: 12 }), parsed tree with index paths and a content_hash

insert-pattern({ post_id: 12, pattern: "pricing-3col", index: 1 }), snapshotted first

Safety and access

What can be undone on Gutenberg, and what costs what.

Recoverable on Gutenberg

  • add-block, update-block, remove-block, move-block, duplicate-block and insert-pattern each snapshot the post before writing.
  • rollback-operation restores the exact previous content, per change or for the whole session.
  • A write is verified by re-reading the stored content, and a mismatch is reverted automatically.

Gutenberg limits and opt-ins

  • The edit tools refuse a stale expected_hash, so an agent must re-read the post after any other change.
  • If the content does not survive a parse and serialize round trip, surgical edits are refused. Use update-blocks to replace the whole content instead.
  • update-block replaces the attrs object whole, so read the block first. inner_html is refused on a block that has inner blocks.
  • Freeform content with no block name cannot be updated surgically.

Free or Pro: All of the above is in the free plugin: parse-blocks, serialize-blocks, convert-html-to-blocks, list-block-types, get-block-type, the six surgical edit tools, list-patterns and insert-pattern. Pro adds the block suite pair for Kadence Blocks, GenerateBlocks, Spectra and others, and a custom block builder. Neither is needed to edit core blocks.

In the free plugin

The Gutenberg integration is in the free plugin.

The core Gutenberg tools ship in the free, GPL plugin with the full snapshot and undo engine, and no trial clock. Pro adds 133 more tools, including Elementor deep editing, the other page builders, the forms adapter pack and, for some integrations, extra operations. The pricing page lists what each tier includes.

Frequently asked

Gutenberg MCP: questions, answered.

Is Gutenberg editing free?

Yes. Because Gutenberg ships with WordPress, this works on a stock install with no page builder and no paid plan.

How does it avoid mangling markup?

Tools address blocks by index path on the parsed tree, not raw find-and-replace on serialized HTML.

What is the expected_hash for?

It is the sha256 of the post content as read by parse-blocks. Block paths are only valid for that exact content, so an edit with an old hash is refused as stale. This stops an agent from changing block 3 after someone else added a block above it.

Can the Gutenberg integration edit blocks inside columns or groups?

Yes. The path is a list of indexes, one per nesting level, so [2,0,1] means the second inner block of the first inner block of the third top-level block. The tree from parse-blocks shows each path, and the write touches only that block.

What does convert-html-to-blocks do with markup it does not recognize?

It maps headings, paragraphs and other known elements to core blocks, and wraps anything it cannot map in a core HTML block so no content is lost. The tool only returns markup. It does not write to any post, so it needs no snapshot.

Is the custom block builder free?

No. create-custom-block and the other builder tools, which make a Gutenberg block from a validated data spec, are part of WP MCP Pro. Editing the core and plugin blocks that already exist on the site stays free.

Is there an AI agent for Gutenberg?

Yes, through WP MCP rather than Gutenberg itself. An agent you choose, such as Claude or Cursor, can read a post's block tree with an index path per block. WP MCP is a separate plugin, not a built-in AI feature of Gutenberg. On the undo side: add-block, update-block, remove-block, move-block, duplicate-block and insert-pattern each snapshot the post before writing.

Point your AI at Gutenberg.