RankMath SEO

RankMath stores its SEO data as WordPress post meta (rank_math_*). The MCP exposes that through two channels you pick per site:

• REST (default, no plugin) — works only if RankMath has registered its meta keys for REST API on your site (register_meta with show_in_rest). Some setups silently drop writes — if set_seo_meta returns seo: {}, switch to Plugin channel.
• Plugin (companion bridge) — superset of REST: meta, structured-data schema, redirects, sitemap. Bypasses REST registration entirely via update_post_meta, so meta writes always succeed.

Picking “Plugin” does not disable REST tools — get_seo_meta / set_seo_meta still work, they just go through the bridge endpoint (/sn-rm/v1/meta) instead of /wp/v2/posts/:id. Picking “Plugin” is strictly the “more features + more reliable” choice.

Guardrail: SEO meta and schema are editable on draft / scheduled posts only by default. The server refuses to touch a published post (E_FORBIDDEN_OP) — unpublish it to a draft first. This matches the project-wide no-publish / no-delete rule. There is no delete tool for redirects or schema.

Opt-in: A super-admin can toggle Allow SEO meta + schema edits on already-published posts in the site’s Danger Zone. When on, set_seo_meta / set_seo_schema work on live posts. The flag is independent of allow_publish; see Publishing & preview branches.

Enable it per site

In /admin/sites → edit a WordPress site → RankMath SEO:

1. Tick Enable RankMath SEO tools.
2. Pick a Channel:
   • REST API meta — nothing else to install.
   • Companion plugin — also install the bridge (below) for schema, redirects, sitemap.

When a site has RankMath disabled, every RankMath tool refuses at runtime with E_RANKMATH_DISABLED.

Tools

Tool	Channel	Purpose
get_seo_meta	REST	Read title / description / keyword / robots / canonical / OG
set_seo_meta	REST	Set any of those fields (draft/scheduled only)
set_seo_schema	Plugin	Set rank_math_schema_* structured data
set_seo_redirect	Plugin	Upsert a redirect (source → destination, default 301)
get_sitemap_status	Plugin	Read the sitemap URL; rebuild=true invalidates its cache
diagnose_site	—	Reports whether RankMath + the bridge plugin are installed

REST tools work in either channel. The plugin tools require the site’s channel to be plugin and the bridge installed, else E_RANKMATH_PLUGIN_REQUIRED.

The companion plugin

For schema / redirects / sitemap, install seo-navigator-rankmath (in wp-plugins/seo-navigator-rankmath/ of the server repo) on the WordPress site, alongside RankMath itself.

It registers a small REST namespace /wp-json/sn-rm/v1/ (status, schema, redirect, sitemap), each route gated by the edit_posts capability — the same trust model as the core meta channel. It never deletes content; redirects are upserted and schema is set on drafts only.

Run diagnose_site to confirm both RankMath and the bridge are present:

"rankmath": {
  "active": true,
  "version": "1.0.210",
  "bridge_installed": true
}

How calls are routed

For each tool call, the server resolves the channel from the site’s rankmath_mode column (set in the admin form):

• rankmath_mode = 'rest' — meta tools call WordPress core /wp/v2/posts/:id (or /pages/:id) with the rank_math_* meta fields. Schema / redirect / sitemap tools refuse with E_RANKMATH_PLUGIN_REQUIRED.
• rankmath_mode = 'plugin' — meta tools call the bridge namespace /wp-json/sn-rm/v1/meta. Schema / redirect / sitemap tools go to their dedicated bridge routes. The bridge bypasses REST registration entirely, so writes always land in wp_postmeta.

When allow_seo_on_published is on AND the target post’s status='publish':

1. The server still routes through the same channel as above.
2. The bridge accepts an extra allow_published: true flag, which lifts its own server-side guardrail.
3. The audit log row for the call carries _published: true in args_json, so you can filter the /admin/audit view to see which live posts were touched.

Calling diagnose_site returns the resolved values:

"rankmath": {
  "active": true,
  "version": "1.0.210",
  "bridge_installed": true,
  "enabled": true,
  "mode": "plugin"
}

enabled + mode come from the site row in D1; active + version + bridge_installed come from probing the WordPress install.

Examples

Set the SEO title and meta description on draft post 128 of acme-blog: title “Best Running Shoes 2026”, description “Our hand-tested picks…”, focus keyword “running shoes”.

Claude calls set_seo_meta with { site_id: "acme-blog", post_id: "128", title, description, focus_keyword }. If post 128 is already published, the call is refused.

Add a 301 redirect from /old-pricing to /pricing on acme-blog.

Claude calls set_seo_redirect (plugin channel required).

Rebuild the sitemap for acme-blog.

Claude calls get_sitemap_status with rebuild: true.

Error reference

Code	Meaning
E_RANKMATH_DISABLED	The site has RankMath turned off in the admin form.
E_RANKMATH_PLUGIN_REQUIRED	A schema/redirect/sitemap tool was called but the site’s channel is rest, or the bridge isn’t installed.
E_FORBIDDEN_OP	Tried to set meta/schema on a published post. Unpublish to draft first.
E_NOT_SUPPORTED	Called on a non-WordPress site.