区块级MCP工具

Requirements

• Node.js ≥ 20
• WordPress ≥ 6.0 with Application Passwords enabled
• PHP ≥ 7.4
• HTTPS (required by WordPress for Application Password authentication)

1. Install the WordPress plugin

Easiest — download the latest ZIP: gk-block-mcp.zip (auto-built from main on every push).

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

Or copy wordpress-plugin/gk-block-mcp/ to your site's wp-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

3. Manual setup (advanced)

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 the edit_posts capability; write endpoints require edit_post on 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:

{
  "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"
      }
    }
  }
}

Restart your MCP client. Run npm run inspect to test the tools interactively.

Quick Start

Examples

Update a heading by URL

"Change the H2 'Welcome' on /about/ to 'About Us'."

1. resolve_url({ url: "/about/" }) → post ID
2. get_page_blocks({ post_id, outline: true }) → finds heading at path: [4], ref blk_a3f2c1q9
3. edit_block_tree({ post_id, op: "update-attrs", ref: "blk_a3f2c1q9", attributes: { content: "About Us" } })

Auto-transform updates both the content attribute and the inner <h2> text. Revision created.

Chained edit workflow (where refs shine)

"On the homepage: delete the third paragraph, change the next H2 to H3, and add a CTA button after it."

1. get_page_blocks({ post_id }) once — capture refs for all three target blocks
2. delete_block({ post_id, ref: <para-ref> })
3. edit_block_tree({ post_id, op: "update-attrs", ref: <heading-ref>, attributes: { level: 3 } })
4. insert_blocks({ post_id, after_ref: <heading-ref>, blocks: [{ name: "core/buttons", … }] })

With path-based addressing, the agent would need to re-fetch between every step. With refs, one read covers the whole chain.

Author and publish a doc

1. list_terms({ taxonomy: "category", search: "Documentation" }) → category ID
2. create_post({ title: "Getting Started", status: "draft", categories: [<id>], blocks: [...] }) → post ID
3. upload_media({ path: "/tmp/screenshot.png", alt_text: "...", post_id }) → attachment ID + URL
4. insert_blocks({ post_id, after_top_level: 0, blocks: [{ name: "core/image", attributes: { id: <atch>, url, alt: "..." } }] })
5. yoast_update_seo({ post_id, title: "...", description: "...", focus_keyword: "..." })
6. update_post({ post_id, status: "publish" })

4. (Optional) Tune the settings

When the plugin is active, an admin page appears at Settings → Block MCP. The defaults work out of the box, but it's worth a look — this is where you decide which blocks AI agents are allowed to write, what to suggest as replacements, and which post types create_post can target.

See the Configuration section below for the full breakdown.

Configuration

Everything in this section is editable at Settings → Block MCP in WordPress admin. Defaults are sensible — none of this is required to get started.

Compared to other WordPress MCPs

The WordPress MCP space is small, and Block MCP is the only one operating at the block-tree layer. The other projects work at different layers and target different workflows — they're often complementary rather than head-to-head, but the agent-loop bench above shows they don't all produce correct results when asked to edit a block.

InstaWP/mcp-wp — A REST-API-wrapping MCP that operates on whole posts, plus broad coverage of users, comments, media, plugins, and plugin-repo search. Standout feature: multi-site management from one MCP instance. Reach for it when you need post-level CRUD across many sites or general-purpose WordPress administration. Not block-aware: editing a single heading inside a long page means reading and rewriting the entire post, and the round-trip through wp/v2's update_page strips every `` block marker. In our bench it failed validation on 7 of 9 trials across Haiku/Sonnet/Opus.

AI Engine Pro — Self-hosted MCP server inside WordPress (Streamable HTTP at /wp-json/mcp/v1/http), built by Meow Apps and the most-installed WordPress AI plugin (100K+). Free tier exposes posts/comments/users/media as MCP tools; Pro adds an Editor Assistant sidebar and additional MCP plumbing. Its wp_alter_post tool is block-aware — block-comment markers survive — but it can desync the block's declared attributes from its innerHTML (e.g., comment marker still says level: 2 while the inner tag is <h3>), and the block editor flags that as broken too. Sonnet and Opus retry until consistent and pass; Haiku sometimes gives up at 7–12 tool calls. 8 of 9 in the bench.

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 edit blocks — 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.

These can coexist. Block MCP could (and likely will) be exposed through the official adapter as registered abilities once that path matures — same logic, blessed plumbing. See issues for the roadmap.