WordPress Block MCP

Extract repeated sections into a reusable pattern, then reference it. Creates a pattern (a wp_block post) from either structured blocks (validated the same way as create_post — legacy blocks rejected) or raw content — exactly one of the two. sync_status:"synced" (default) means edits to the pattern update every page that references it; "unsynced" creates an independent one-off starting point instead. For a synced pattern, the response includes a ready-to-insert reference snippet ({blockName:"core/block", attrs:{ref}}) for insert_blocks. For an unsynced pattern, reference is omitted (that shape is a live, propagating synced-block reference and would be wrong for a one-off) — instead the response includes insert_hint ({tool:"insert_pattern", params:{pattern_id, synced:false}}) pointing at the correct follow-up call.

Create a new post or page. Returns ID, slug, permalink, and edit link. Provide either content (raw HTML or block markup) OR blocks (structured), not both. Status defaults to draft. Use update_post for trash transitions.

Remove block(s) by top_level_counter OR by ref. Provide exactly one. For core/block, removes the reference only — not the source pattern.

Run one structural op on a nested block tree. Ops: update-attrs, update-html, replace-block, remove-block, wrap-in-group, unwrap-group, insert-child, duplicate, move. Target the block via ref (stable gk_ref — recommended, survives sibling shifts) OR path (integer array, e.g. [0,2,1]). For move, the destination can be a destination_ref instead of a path. Creates a revision.

Fetch one block by stable ref OR flat_index — returns the canonical saved snapshot (inner_html + attributes) from the database. Same shape that update_block / update_blocks (with verbose:true) echo back, so verification reads use the identical contract as the writes that produced them. Lighter than get_page_blocks when you only need to confirm one known block. For dynamic blocks (saved.is_dynamic), inner_html is the stored template, not rendered output.

Get a post's blocks. Pass post_id OR url (server resolves URL — don't shell out). Returns {post_id, summary, blocks[], block_count, warnings}. Each block: {index (flat), top_level_counter? (top-level only), path, ref (stable gk_ref), name, attributes, innerHTML?, dynamic, storage_mode ("static"|"dynamic"|"dual"), preference? (when non-preferred)}. Refs survive sibling shifts — pass them to update_block / delete_block / edit_block_tree to chain mutations without re-fetching. Use outline:true or summary_only:true for cheap inspection.

Single pattern's full block content + metadata. Use after list_patterns.

Post metadata by post_id, url, or slug+post_type. Returns {post_id, title, status, post_url, edit_url, modified, created, parent_id, author, mime_type, comment_count}. Replaces wp eval / get_permalink() shell-outs.

Site-wide block + pattern inventory: usage counts, namespace totals, pattern reference counts, legacy patterns.

A single template or template part's metadata, raw block markup (content), and parsed blocks. Use after list_templates. wp_id tells you whether a database override shadows the theme file — null means the id currently resolves to the theme file itself.

Insert top-level blocks into a post.

POSITIONING — use exactly ONE anchor (any other key, e.g. after, before, position, is rejected):

• before_ref / after_ref — gk_ref from get_page_blocks. Recommended: refs survive sibling shifts.
• before_top_level / after_top_level — top_level_counter position.
• Prepend at the very top: before_top_level: 0. Append at the end: omit all anchors.

CONTENT — legacy-tier blocks are rejected per the site policy. Blocks with HTML-sourced attributes (e.g. core/paragraph content, core/image url) must include matching innerHTML; attribute-only inserts fail with inner_html_required.

VERIFY — the response's inserted[] returns ref, path, and top_level_counter: confirm the block landed where you intended before moving on. The refs let you chain edit_block_tree without re-reading.

Insert a pattern. Default synced=true inserts a core/block reference (edits to source update all pages); synced=false inlines blocks for per-page edits. NOTE: registered (non-numeric) patterns cannot be synced — server forces synced=false. Response includes synced (actual mode used) so you can detect the override.

Registered block bindings sources — what a block's metadata.bindings attribute can reference to pull an attribute value dynamically (e.g. core/post-meta, core/pattern-overrides). Returns {sources: [{name, label, uses_context?}], note?}; note is present with sources empty on WordPress below 6.5.

Registered block types with per-block preference (tier + replacement), storage_mode ("static"|"dynamic"|"dual"), usage (count + post_count), attributes (incl. source declarations), and a top-level guidance summary grouped by tier. styles lists valid is-style-* variations — check it before setting an is-style-* className; parent/ancestor/allowed_blocks are nesting constraints — respect them when nesting. Pass include_supports:true for the full supports object. Filters: namespace, category, tier, storage_mode, search (name/title substring), preferred_only, usage_only. Pagination: limit/offset → next_offset. Returns {block_types[], count, total, offset, next_offset, guidance}.

Block patterns sorted by preference score. Check before building from scratch. Server respects limit; offset slices client-side. Reference counts are cached for 1 hour — pass refresh:true to rebuild. category filters differently by pattern kind: registered patterns are matched against their declared pattern categories, while synced patterns (no separate category taxonomy) are matched against the block categories actually used in their content. The response's top-level categories lists the registered pattern-category vocabulary.

Search posts by title/content with pagination. Returns {posts: [{post_id, title, slug, post_type, post_status, post_url, modified}], total, page, per_page, total_pages}. Use instead of wp post list / wp-json.

List the active theme's templates (page layouts like "single", "archive") or template parts (reusable regions like "header", "footer") — works on a theme without a full block-theme structure too, as long as it has real templates/parts. Each row includes wp_id — present (non-null) when a database post already backs the template (an override shadowing a theme file, or a fully custom template with none); null means it currently resolves purely to the theme file. Every template is editable via update_template regardless — a null wp_id just means calling it creates the override rather than updating an existing one. Returns an empty list with a note only when there is truly nothing to list.

List terms in a taxonomy (default: category). Useful for discovering category and tag IDs to pass to create_post or update_post.

Atomic single-revision swap of N top-level blocks for M new blocks (M can be 0, 1, or N). Safer than delete+insert (no half-written intermediate state). Distinct from rewrite_post_blocks (which replaces the entire post).

Delete a template's database override, reverting it to the theme file. Requires the site's "Let the assistant edit theme templates" toggle (off by default; returns a 403 with an actionable message when off). 404s when the id has no override to remove.

URL or path → post ID. Accepts full URLs or site-relative paths. Run this before get_page_blocks / update_block / edit_block_tree when you only have a URL.

Restore a post to a revision. Pass before_revision_id from a prior write to UNDO that write; pass revision_id to REDO it.

Replace ALL blocks on a page in one revision. Use for major restructuring; prefer update_block / insert_blocks / replace_block_range for edits.

Walk every published post and persist a block_name → "static"|"dynamic"|"dual" map (option gk_block_api_storage_modes). Slow on large sites; rate-limited to 1/hr. After this runs, get_page_blocks storage_mode annotations and dual-storage write enforcement use the live classification. Returns {scanned_posts, unique_blocks, classification, dual_count, dynamic_count, static_count}.

Update one block by flat_index OR by ref (stable gk_ref from get_page_blocks). Provide exactly one targeting field. Refs are recommended for chained mutations because they survive sibling shifts. attributes are SHALLOW-merged at top level — pass full arrays, not deltas. innerHTML replaces atomically. For dual-storage blocks (e.g. yoast/faq-block) you MUST send both fields together; innerHTML-only is rejected. Response includes saved.inner_html and saved.attributes — the canonical post-save snapshot from the database. Do not fetch the public page to verify edits.

Update N independent blocks atomically in ONE revision. Each item targets one block by ref (recommended) or flat_index, with attributes and/or innerHTML. Validation is all-or-nothing: any stale ref / out-of-range index / dual-storage rejection / duplicate target aborts the batch with itemized errors — no partial writes hit disk. Max 50 items per call. Counts as ONE write against the per-post rate limit. Use this instead of looping update_block when fixing multiple blocks on the same post — keeps revision history clean. Pass verbose: true to include saved.inner_html + saved.attributes per result for per-item verification without a re-read.

Partial update of post metadata, status, or terms. Block content edits stay on the per-block tools. Use status: "trash" to trash; any non-trash status untrashes a trashed post. At least one mutating field besides post_id is required.

Replace a template or template part's entire content — whole-template replacement, like rewrite_post_blocks, not a per-block edit. Requires the site's "Let the assistant edit theme templates" toggle (off by default; returns a 403 with an actionable message when off). If the id currently resolves to the theme file (wp_id: null), a database override is created (override_created: true) and the theme file itself is never touched. content and blocks are mutually exclusive — blocks goes through the same registry/tier/dual-storage validation as any other structured-block write. Use reset_template to revert.

Upload an item to the WordPress media library. Provide exactly one of: path (local filesystem on the MCP host, sent as multipart), url (server-side sideload, 25 MB cap), or data_base64 (with filename). Returns the attachment ID and URL ready for core/image blocks.

Update Yoast SEO fields on multiple posts in one call. Each item must include post_id plus any fields to update. Response preserves order.

Read all Yoast SEO metadata for a post or page (title, description, robots, Open Graph, Twitter card, schema types, cornerstone flag, breadcrumb, redirect, scores, primary terms).

Update one or more Yoast SEO fields on a single post or page. Only supplied fields are written. noindex is tri-state (true / false / null).