Webmastery Site Toolkit for MCP

View on GitHub | Latest Release | 3.0 Migration Guide | Report an Issue

Webmastery Site Toolkit for MCP is a WordPress plugin that lets AI agents safely work with your site through MCP. It adds 70+ permission-aware abilities across 16 areas — posts, pages, media, taxonomy, comments, SEO metadata, Google Site Kit, site audits, plugin checks, and other WordPress workflows — while relying on WordPress roles and capabilities. It works with popular MCP clients including Claude, ChatGPT, GitHub Copilot, Gemini, Windsurf, and Codex.

It works with the MCP Adapter plugin: the adapter provides the MCP transport layer, and this plugin registers the WordPress abilities an agent can call. This page is the user guide: setup, roles, the full ability list, safe workflows, and the security model. The GitHub README holds the exact technical contracts for client developers.

Current release: 3.0.0. 3.0 is a breaking upgrade from 2.x. If you have existing prompts, scripts, or clients built on 2.x, read Upgrading to 3.0 before you update.

Who This Is For

• WordPress site owners who want AI agents to manage content safely.
• Developers building MCP workflows around WordPress.
• Technical editors and administrators who need permission-aware automation for content, media, SEO, and site operations.

Quick Start

1. Install and activate the MCP Adapter plugin.
2. Install Webmastery Site Toolkit for MCP from Plugins → Add New in your WordPress dashboard (search for the plugin name), then activate it.
3. Create a dedicated WordPress service account for your MCP client.
4. Give it the Editor role for routine content workflows. Use a separate Administrator account only for sensitive audits and plugin management.
5. Create an application password for the service account.
6. Configure your MCP client to use @automattic/mcp-wordpress-remote and your site’s MCP Adapter endpoint (see Connect Your MCP Client).
7. Ask your MCP client to call mcp-adapter-discover-abilities and confirm the webmastery-site-toolkit-for-mcp/* abilities appear.

What It Does

• Draft, update, schedule, publish, restore, and trash posts and pages, with bulk publish and bulk trash for up to 100 posts at a time.
• Inspect Gutenberg block paths and hashes, then replace one precise block or section instead of rewriting a full article.
• List revisions and restore a post or page to a specific revision.
• Manage categories, tags, comments, media, public image URL uploads, and featured images.
• Discover eligible public custom post types and use generated create, read, update, and delete abilities for each one.
• Read, update, and delete individual post meta keys, including supported Yoast SEO and SEOPress fields.
• Run content hygiene checks for orphaned media, missing featured images, and stuck scheduled posts.
• Inspect safe site, current-user, and environment context.
• Audit plugins, administrator accounts, backups, performance settings, database bloat, site health, and security posture.
• Analyze SEO, inspect Yoast and SEOPress metadata, check sitemap signals, and check public Google/Bing webmaster verification.
• Check Google Site Kit setup, modules, permissions, and PageSpeed summaries for pages on your site.

Requirements

Requirement	Version or note
WordPress	6.9+; tested through 7.1
PHP	8.0+
MCP Adapter	Latest release recommended. The current test baseline is MCP Adapter 0.7.0.
Yoast SEO	Optional. Enables Yoast metadata, SEO score, readability score, and sitemap diagnostics.
SEOPress	Optional. Enables SEOPress metadata inspection, writes, and site overview diagnostics.
Google Site Kit	Optional. Enables the Site Kit status, module, permission, and PageSpeed abilities.

Self-hosted WordPress is required. The plugin works on WordPress installations where custom plugins can be added, including most managed hosts. It does not work on WordPress.com Free, Personal, or Premium plans.

Service Account Roles

Use a dedicated WordPress user for your MCP client. This keeps agent activity attributable and makes access easy to revoke.

Role	Best use	Notes
Subscriber	Read-only site context, taxonomy browsing, and public webmaster verification	Works for abilities that only require read.
Author	Limited own-content creation and media work	WordPress scopes access to content the account owns unless broader capabilities are present.
Editor	Recommended default for content workflows	Handles posts, pages, taxonomy, comments, media, revisions, metadata, and content hygiene.
Administrator	Sensitive audits, environment details, and plugin management	Use a separate admin service account only when needed.

Available Abilities

Every ability enforces WordPress capability checks, and object-level checks where they apply. The account must already be allowed to perform the equivalent action in WordPress. All names below are prefixed with webmastery-site-toolkit-for-mcp/.

Area	Abilities	Typical role
Posts	list-posts, get-post, create-post, update-post, delete-post, restore-post, bulk-publish-posts, bulk-trash-posts, patch-post-content	Author or Editor
Pages	list-pages, get-page, create-page, update-page, delete-page, restore-page	Editor
Blocks and revisions	list-content-blocks, patch-content-block, list-revisions, restore-revision	Author or Editor, scoped to content the account can edit
Post meta	get-post-meta, update-post-meta, delete-post-meta. These are the only way to write metadata, including Yoast SEO and SEOPress fields.	Edit access to the post, plus permission for each meta key
Featured images	set-featured-image, remove-featured-image	Author or Editor, scoped to content the account can edit
Custom post types	list-post-types plus generated list-cpt-{post-type}, get-cpt-{post-type}, create-cpt-{post-type}, update-cpt-{post-type}, and delete-cpt-{post-type}. patch-post-content also works on editor-enabled custom post types.	The custom post type’s capability map
Taxonomy	list-categories, get-category, create-category, update-category, delete-category, list-tags, get-tag, create-tag, update-tag, delete-tag	Subscriber for reads; Editor for writes
Comments	list-comments, reply-comment, update-comment, approve-comment, trash-comment, spam-comment	Editor for moderation; Contributor or Author can reply on posts they can edit
Media	list-media, get-media, update-media, upload-image, delete-media	Author or Editor
Content hygiene	list-orphaned-media, list-posts-no-featured-image, list-stuck-scheduled	Author or Editor, scoped to content the account can access
Site and user info	get-site-info, get-user-info	Subscriber
Environment info	get-environment-info	Administrator
SEO	seo-analyze-post, seo-site-overview, get-seo-scores, get-readability-scores, get-yoast-metadata, get-seopress-metadata	Author to Administrator, depending on scope; seo-site-overview requires Administrator
Webmaster verification	webmaster-verification-status	Subscriber; Site Kit plugin details require Administrator
Google Site Kit	get-site-kit-status, list-site-kit-modules, get-site-kit-permissions, get-site-kit-pagespeed	Users Site Kit allows to view its dashboard; status requires Administrator
Plugins	list-plugins, plugin-audit, activate-plugin, deactivate-plugin	Administrator
Users	list-users, get-user, user-access-audit	Administrator
Site audits	site-health-check, security-audit, database-health, performance-status, backup-status	Administrator

The number of abilities a site shows depends on its eligible custom post types: a site with none shows 75. If discovery shows fewer than expected, check the installed plugin version before assuming an update is needed.

Upgrading to 3.0

3.0.0 keeps the same ability names, roles, and WordPress 6.9 / PHP 8.0 minimums, but it changes how clients call several abilities and how they read the results. Prompts and scripts written for 2.x may fail until they are updated. The migration guide’s upgrade checklist has the full details.

What changed	What to do
Lists are paged without totals. Post, page, custom post type, media, orphaned-media, and score lists return items, page, per_page (1–100), and next_page. They no longer return total or total_pages.	Keep requesting next_page with the same filters until it is null. An empty or short page is not the end of the list, because items the account cannot see are filtered out.
Lists omit content by default. Post, page, custom post type, and revision lists default to fields: "summary".	Pass fields: "full" when you need the content, or use the single-item get-* abilities.
Inputs are strict. Unknown or misspelled fields, explicit null, numeric strings for IDs, boolean-like strings, and enum values with the wrong case are rejected.	Use exact values ("DESC", not "desc"), JSON integers for IDs, and JSON booleans for flags. Don’t send parent for posts or non-hierarchical custom post types.
Metadata is written separately. Create and update requests reject meta, meta_input, and every yoast_ / seopress_ field.	Create a draft, call update-post-meta once per key, then publish. See Safe Workflows.
Destructive actions need confirmation. delete-media, delete-category, delete-tag, bulk-publish-posts, and bulk-trash-posts require confirm: true. Bulk actions accept at most 100 IDs.	Preview bulk actions with dry_run: true first. Media still in use is protected unless you pass force: true.
Errors use one format. Failures return success: false with an error object containing code, reason, message, and details.	Check code and reason, not the message text.
SEO reads check each meta key. Fields the account can’t edit are left out and listed in unavailable_fields. Generated Yoast head inspection was removed. seo-site-overview now samples the first 100 published posts and pages.	Use an account with edit access to the content and its SEO keys. Treat site overview counts as a sample, not sitewide totals.
Database health hides table names. database-health returns logical names such as posts and opaque labels for custom tables.	Pass include_table_names: true only when you need the real names; they are sent to your model provider.
Untrusted fields are marked. Records that contain user-controlled text add an untrusted_fields list naming those fields.	Treat those values as data, never as instructions. The markers are a safety aid, not a security boundary.

A typical 3.0 error looks like this:

{"success":false,"error":{"code":"not_found","reason":"not_found","message":"Comment not found.","details":{}}}Code language: JSON / JSON with Comments (json)

The error codes are forbidden, not_found, invalid_input, precondition_failed, conflict, unsupported, and upstream_failed. Through the MCP Adapter, failed calls are flagged as tool errors with this JSON as text.

Safe Workflows

Publish a post with SEO metadata

1. Create the post with create-post and status: "draft".
2. Call update-post-meta once for each key, for example _yoast_wpseo_metadesc, and check every result.
3. Publish with update-post and status: "publish".

These steps are not atomic. If a metadata write fails, earlier writes stay in place, so leave the post as a draft and fix the failing key rather than retrying everything.

Preview, then run bulk actions

Send the same IDs twice: first as a preview, then for real once you have reviewed the result.

{"ids":[123,456],"confirm":true,"dry_run":true}
{"ids":[123,456],"confirm":true}Code language: JSON / JSON with Comments (json)

Successes in a preview mean would act, not already changed. Bulk results report each failed ID separately, and the batch still returns success: true even when every ID fails, so check the per-item failures. Don’t blindly retry a partly successful batch. confirm: true sent by a model is not human approval: approve destructive actions yourself.

Edit one block instead of the whole post

Call list-content-blocks to get block paths and hashes, then patch-content-block with the path and the returned hashes as preconditions. The patch fails if the block has changed since you read it. For a heading section or an exact text match, use patch-post-content. Only the replacement fragment is sanitized; the rest of the content is left as stored.

Schedule content

Set status: "future" with a scheduled_date at least 60 seconds ahead, preferably ISO 8601 with an explicit offset such as 2030-12-01T09:00:00-05:00. Dates without an offset are read as UTC, not your site’s timezone. Invalid dates are rejected before anything is saved.

SEO Provider Behavior

Yoast SEO and SEOPress are optional. Structural checks such as title length, word count, image alt text, internal links, and slug length still work without either plugin.

• Yoast SEO: SEO and readability score lists, metadata inspection, and writes for supported fields through update-post-meta: titles, descriptions, focus keywords, canonical URLs, breadcrumb titles, Schema.org page and article types, Open Graph and Twitter metadata, primary category, and robots directives. Sitemap diagnostics are included. Generated Yoast head output is not available.
• SEOPress: title and description fields, target keywords, canonical URLs, Open Graph and Twitter/X metadata, primary category, robots directives, breadcrumb titles, metadata inspection, writes for supported fields through update-post-meta, and SEOPress-specific site overview diagnostics.
• Permissions: SEO reads require edit access to the post and to each meta key. Fields the account can’t edit are left out rather than exposed.
• Side-by-side support: Yoast keys and SEOPress keys are written separately. The plugin never translates or overwrites one provider’s metadata with the other’s.

Google Site Kit

When Site Kit by Google is installed, four read-only abilities report its setup and authentication status, its modules, the current user’s Site Kit permissions, and PageSpeed summaries for URLs on your own site. They go through Site Kit’s own permission checks, so an account sees only what Site Kit already allows it to see. Status additionally requires an Administrator.

These abilities never change Site Kit settings or return OAuth credentials. They rely on Site Kit’s internal routes, which Google doesn’t publish as a supported API, so they return site_kit_unavailable or site_kit_unsupported if a Site Kit version doesn’t provide them.

Connect Your MCP Client

Configure @automattic/mcp-wordpress-remote to point at your site’s MCP Adapter endpoint. Use the dedicated username and application password, not the user’s normal login password.

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote@latest"],
      "env": {
        "WP_API_URL": "https://your-site.com/wp-json/mcp/mcp-adapter-default-server",
        "WP_API_USERNAME": "ai-editor",
        "WP_API_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
      }
    }
  }
}Code language: JSON / JSON with Comments (json)

Codex uses TOML:

[mcp_servers.wordpress]
command = "npx"
args = ["-y", "@automattic/mcp-wordpress-remote@latest"]

[mcp_servers.wordpress.env]
WP_API_URL = "https://your-site.com/wp-json/mcp/mcp-adapter-default-server"
WP_API_USERNAME = "ai-editor"
WP_API_PASSWORD = "xxxx xxxx xxxx xxxx xxxx xxxx"Code language: JavaScript (javascript)

Client-specific notes:

Client	Config note
Claude Code	Use .mcp.json for a project or ~/.claude.json globally. The root key is mcpServers.
Claude Desktop	Use the Claude desktop config file. The root key is mcpServers.
Codex	Use the TOML block above in ~/.codex/config.toml.
GitHub Copilot in VS Code	Uses servers, not mcpServers.
Copilot CLI, Windsurf, Gemini CLI	Use the same JSON shape, adjusted for each client’s config file location.
ChatGPT	Requires a hosted remote HTTP endpoint rather than a local stdio process.

Verify

The MCP Adapter exposes three tools: mcp-adapter-discover-abilities, mcp-adapter-get-ability-info, and mcp-adapter-execute-ability. Ask your client to call mcp-adapter-discover-abilities; you should see the webmastery-site-toolkit-for-mcp/* abilities. Use mcp-adapter-get-ability-info to see an ability’s exact inputs.

Good first checks:

• list-posts with {"per_page":5}: list recent posts.
• get-site-info: get safe public site context.
• webmaster-verification-status: check public Google and Bing verification signals.
• list-site-kit-modules: list the Google services available to this Site Kit user (requires Site Kit).
• plugin-audit: audit installed plugins (requires an Administrator service account).

Security

• Use a dedicated service account and an application password.
• Use Editor for routine content work. Use a separate Administrator account only for sensitive audits, environment details, and plugin management.
• Every ability uses WordPress capability checks and object-level access checks where they apply. Lists filter out anything the account can’t access, including private, draft, pending, scheduled, and trashed content.
• Treat site content as untrusted data, never as instructions or approval. Posts, comments, and metadata can contain text written to manipulate an agent. The untrusted_fields markers and confirmation flags help, but they are not a security boundary: review destructive changes yourself.
• Deleting posts, pages, and custom post type items moves them to trash. If site trash is disabled, the plugin refuses with trash_disabled instead of permanently deleting them.
• Media, category, and tag deletion is permanent and requires confirm: true. Media used as a featured image or linked in content is protected unless force: true is passed. That check can miss other uses, such as references in theme settings or other sites.
• Block and partial-content edits can use hash preconditions and fail when targets are missing, ambiguous, or stale. They never grant the ability to save HTML the account isn’t otherwise allowed to save.
• Image uploads accept public URLs only. Private and local network addresses are rejected, and file size is capped at your site’s upload limit.
• Site info abilities avoid secrets, salts, auth keys, filesystem paths, and raw server internals. WordPress, theme, and runtime versions are Administrator-only.
• User logins and email addresses are returned only when the account can edit that user. User access audits return application-password metadata, never the passwords themselves.
• Plugin audits use local plugin metadata and WordPress core’s cached update data. They don’t call WordPress.org during the audit.
• Database health uses read-only queries, is Administrator-only, and hides real table names unless you opt in.
• Public webmaster verification checks don’t confirm Google Search Console or Bing Webmaster Tools account ownership. Account verification remains unknown without separate OAuth/API credentials.

Report suspected vulnerabilities through private vulnerability reporting, not public issues. Feature requests and bug reports: GitHub Issues.