Skip to content
SEO Navigator MCP

WordPress prerequisites

This page is the single source of truth for what has to be set up before any of the WordPress workflow pages will work. Skim it once, fix anything that’s missing, then move on to the workflow you care about.

1. The site itself

Section titled “1. The site itself”
  • WordPress 5.5+ (older versions have broken REST behaviour around Application Passwords).
  • REST API reachable at https://<site>/wp-json/. Open the URL in a browser — if you get JSON, you’re good. If you get a 401/403/redirect loop, a security plugin or WAF is blocking REST and you need to allow the path before anything else works.

2. App Password

Section titled “2. App Password”

The worker authenticates against WordPress with HTTP Basic Auth using a WordPress Application Password (NOT your login password — that’s deprecated and often blocked by hosts).

  1. wp-admin → Users → Your profile
  2. Scroll to Application Passwords
  3. Type a name like SEO Navigator MCP → click Add New Application Password
  4. Copy the 24-character password (shown once)
  5. In the worker admin at /admin/sites, click Set app pass on the site row and paste it. The worker stores it encrypted in D1.

The password belongs to a real WP user — that user needs edit_posts and edit_pages capability at minimum. For taxonomy creation, manage_categories helps. Use an account that is an Editor or Administrator role.

3. Site registered in /admin/sites

Section titled “3. Site registered in /admin/sites”

Required fields:

FieldValue
ID (slug)Stable identifier used everywhere — viper-template, acme-blog, etc. Cannot be changed later.
Display nameHuman-readable, free text
Platformwordpress
Base URLhttps://example.com — no trailing slash
WP usernameThe login of the user who issued the app password
Page buildersTick Gutenberg, Elementor, or both (see below)
Default builderThe one Claude uses when not explicitly told which builder to pick
MCP backenddefault (REST API) or wp-mcp-adapter (proxy) — see below

4. Page builders

Section titled “4. Page builders”

If the site has only Gutenberg installed, tick Gutenberg as the default. That covers create_page_draft for the built-in editor + create_page_from_code for the vibe-code-in-chat flow.

If Elementor is also installed and you want to use the template-duplicate workflow:

  • Tick Elementor in the available builders list
  • Pick a default (the one Claude picks when no page_builder arg is sent)
  • If you tick both Gutenberg and Elementor, Claude must pass page_builder=gutenberg or page_builder=elementor explicitly on create_page_draft, OR call list_builders_for_site first to discover which to use. Calls without a builder arg fail with E_BUILDER_REQUIRED.

5. Elementor-specific setup (only if you tick Elementor)

Section titled “5. Elementor-specific setup (only if you tick Elementor)”

The Elementor template-duplicate workflow needs _elementor_data exposed via the REST API. Two ways:

A. default MCP backend — paste this into the active theme’s functions.php:

add_action('rest_api_init', function () {
    register_rest_field('page', 'meta', [
        'get_callback' => function ($obj) {
            return [
                '_elementor_data' => get_post_meta($obj['id'], '_elementor_data', true),
                '_elementor_edit_mode' => get_post_meta($obj['id'], '_elementor_edit_mode', true),
                '_elementor_template_type' => get_post_meta($obj['id'], '_elementor_template_type', true),
            ];
        },
        'schema' => null,
    ]);
});

B. wp-mcp-adapter MCP backend — install the wordpress/mcp-adapter plugin + msrbuilds/elementor-mcp plugin. The adapter exposes Elementor data + 74 widget-level tools through its own MCP endpoint, which the worker proxies. No snippet needed.

Run diagnose_site site_id="<wp-site-id>" to verify the snippet (or the adapter) is detected.

6. Code-first pages — optional WP plugin

Section titled “6. Code-first pages — optional WP plugin”

The create_page_from_code / update_page_from_code tools need a tiny plugin installed on the WP site to emit the inline CSS/JS that the worker attaches to the page as meta.

  1. Download from wp-plugins/seo-navigator-code-page in the worker repo
  2. Upload as a zip in wp-admin → Plugins → Add New → Upload Plugin
  3. Activate
  4. Confirm with diagnose_site site_id="<wp-site-id>" — the code_page_plugin.installed flag must flip to true

Skip this step if you don’t use the vibe-code workflow.

7. Token scope

Section titled “7. Token scope”

The MCP token presented in /mcp calls must have:

  • The site in its allowed_sites (or * wildcard which expands to the user’s user_sites at create time)
  • The tools in its allowed_tools — for the WordPress workflows you’ll typically want:
    • Posts: create_draft, update_draft, schedule_draft, unschedule, get_post, list_drafts, upload_media, list_taxonomies, create_taxonomy
    • Pages: create_page_draft, update_page_draft, schedule_page, list_page_templates, list_builders_for_site
    • Code-first: create_page_from_code, update_page_from_code
    • Diagnostic: diagnose_site, list_sites, get_site, ping_site

Quick-pick Select all in the token form covers everything safe. Quick-pick All except destructive excludes proxy delete-* / publish-* tools (those are filtered out of tools/list anyway, but the quick-pick is belt-and-braces).

delete_astro_route is super-admin only and won’t appear in regular-user token forms.

8. Verify with ping_site + diagnose_site

Section titled “8. Verify with ping_site + diagnose_site”

Once everything looks set, ask Claude:

Ping site viper-template and run diagnose.

Both should return ✅ across the board. If diagnose_site flags something red, fix it before running any other workflow tool. The error message tells you what’s missing.

Next

Section titled “Next”