@adsim/wordpress-mcp-server

v5.3.1

Published

2 months ago

Enterprise WordPress MCP Server — 180 tools, modular architecture, governance, audit trail, WooCommerce, Schema.org, multilingual.

WordPress MCP Server

Enterprise Governance · Audit Trail · Multi-Site · Plugin-Free

The enterprise governance layer for Claude-to-WordPress integrations — secure, auditable, and multi-site.

v5.3.1 Enterprise · 176 tools · ~1109 Vitest tests · GitHub Actions CI

Architecture

┌─────────────────────────────┐
│       Claude Client         │  Claude Desktop · Claude Code · Any MCP client
└──────────────┬──────────────┘
               │ MCP Protocol (stdio or HTTP Streamable)
┌──────────────▼──────────────┐
│    WordPress MCP Server     │  Node.js · Standalone · No WordPress plugin
├─────────────────────────────┤
│  index.js (~498 lines)      │  Orchestration only: MCP transport, enterprise controls, dispatch
├─────────────────────────────┤
│  src/tools/ (18 modules)    │  175 tool definitions + handlers by category
├─────────────────────────────┤
│  src/shared/                │  utils · api · audit · governance · context
├─────────────────────────────┤
│  src/plugins/               │  PluginRegistry · ACF · auto-detected via REST namespaces
├─────────────────────────────┤
│  WP_TOOL_CATEGORIES Filter  │  Load only the categories you need (~4-9k tokens vs ~20k)
├─────────────────────────────┤
│  Execution Controls         │  Read-only · Draft-only · Plugin mgmt · Type/status allowlists
├─────────────────────────────┤
│  Audit Logging              │  JSON on stderr · 79+ instrumentation points
├─────────────────────────────┤
│  Rate Limiting              │  Client-side · Configurable per-minute cap
├─────────────────────────────┤
│  HTTP Transport             │  Bearer auth · Session management · Origin validation
└──────────────┬──────────────┘
               │ HTTPS + WordPress Application Password (Basic Auth over TLS)
┌──────────────▼──────────────┐
│    WordPress REST API       │  Single site or multi-target
├─────────────────────────────┤
│  MCP Diagnostics mu-plugin  │  Optional · Debug log · Cron · Schema · Security endpoints
└─────────────────────────────┘

Why This Server

Most WordPress MCP servers focus on what you can do. This one focuses on what you should be allowed to do — and who can verify it happened.

In regulated environments — financial services, healthcare, legal, government — AI-powered content operations need guardrails. This server provides them out of the box: read-only mode for monitoring, draft-only mode for review workflows, structured audit logs for compliance, and multi-site management for agencies operating across client portfolios.

No composer, no PHP build, no WordPress admin plugin. Point it at any WordPress site with an Application Password, configure your execution policy, and connect your Claude client.

With 173 tools across 18 categories and WP_TOOL_CATEGORIES, agencies can load only the tools they need per deployment — reducing the ListTools context from ~20,000 tokens to as low as ~4,000 tokens, saving cost and improving response quality.

Safety Model

This server is designed for safe operation in production environments:

Default non-destructive — delete operations must be explicitly enabled
Configurable execution modes — read-only, draft-only, or full access per deployment
Pre-flight enforcement — all guardrails checked before any API call is made
Full audit trail — every action logged with timestamp, target, outcome, and latency
Credential isolation — secrets never appear in logs or error outputs
Multi-tenant ready — independent auth and config per WordPress target

Data Retention

The server does not store or persist WordPress content. All processing is stateless — content flows through the server and is never cached, written to disk, or retained in memory beyond the scope of a single tool invocation. Audit logs are emitted to stderr in real-time and can be disabled (WP_AUDIT_LOG=off) or redirected to any logging pipeline based on deployment requirements. Zero data retention by design.

Quick Start

Requirements

Node.js >= 18
WordPress site with REST API enabled (default since WP 4.7)
WordPress Application Password (WP 5.6+)
HTTPS endpoint (required for production)
WooCommerce 3.5+ (optional, for WooCommerce tools)

Install from npm (recommended)

# Run directly — no install needed
npx -y @adsim/wordpress-mcp-server

# Or install globally
npm install -g @adsim/wordpress-mcp-server

Install from GitHub

git clone https://github.com/GeorgesAdSim/wordpress-mcp-server.git
cd wordpress-mcp-server
npm install

Configure

Create a .env file:

WP_API_URL=https://yoursite.com
WP_API_USERNAME=your-username
WP_API_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx

# Optional: WooCommerce (generate at WooCommerce → Settings → Advanced → REST API)
WC_CONSUMER_KEY=ck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
WC_CONSUMER_SECRET=cs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Context optimization (optional)
WP_TOOL_CATEGORIES=seo,content,schema    # Load specific categories only
WP_COMPACT_JSON=true                      # Compact JSON output (default)

To generate an Application Password: WordPress Admin → Users → Profile → Application Passwords → Add New.

Connect to Claude Desktop

Add to claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "@adsim/wordpress-mcp-server"],
      "env": {
        "WP_API_URL": "https://yoursite.com",
        "WP_API_USERNAME": "your-username",
        "WP_API_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
      }
    }
  }
}

Connect to Claude Code

claude mcp add wordpress \
  -e WP_API_URL=https://yoursite.com \
  -e WP_API_USERNAME=your-username \
  -e WP_API_PASSWORD="xxxx xxxx xxxx xxxx xxxx xxxx" \
  -- npx -y @adsim/wordpress-mcp-server

HTTP Streamable Transport

New in v3.0.0 — Run the server over HTTP instead of (or alongside) stdio, following the MCP spec 2025-03-26.

Start in HTTP mode

MCP_TRANSPORT=http \
MCP_HTTP_PORT=3000 \
MCP_AUTH_TOKEN=your-secret-token \
WP_API_URL=https://yoursite.com \
WP_API_USERNAME=your-username \
WP_API_PASSWORD="xxxx xxxx xxxx xxxx" \
npx -y @adsim/wordpress-mcp-server

Dual mode (stdio + HTTP simultaneously)

MCP_TRANSPORT=http \
MCP_DUAL_MODE=true \
MCP_AUTH_TOKEN=your-secret-token \
npx -y @adsim/wordpress-mcp-server

HTTP environment variables

| Variable | Default | Description | |-----------------------|-------------|------------------------------------------------------| | MCP_TRANSPORT | stdio | Set to http to enable HTTP Streamable transport | | MCP_HTTP_PORT | 3000 | HTTP server port | | MCP_HTTP_HOST | 127.0.0.1 | Bind address | | MCP_AUTH_TOKEN | (none) | Bearer token for authentication (required in HTTP mode) | | MCP_ALLOWED_ORIGINS | (none) | Comma-separated allowed origins (anti-DNS-rebinding) | | MCP_SESSION_TIMEOUT_MS | 3600000 | Session TTL in milliseconds (1 hour) | | MCP_DUAL_MODE | false | Run stdio and HTTP transports simultaneously |

Health check

curl http://localhost:3000/health
# → { "status": "ok", "version": "4.14.0", "transport": "http" }

Connect an MCP client via HTTP

{
  "mcpServers": {
    "wordpress-http": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-token"
      }
    }
  }
}

MCPB Bundle — Claude Desktop One-Click Install

New in v3.1.0 — Package the server as a .mcpb bundle for Claude Desktop distribution.

The bundle stores WordPress credentials securely in the OS keychain (sensitive: true) — no manual JSON editing required.

Build the bundle

npm run build:mcpb
# → wordpress-mcp-server.mcpb

Install in Claude Desktop

Double-click wordpress-mcp-server.mcpb — Claude Desktop will prompt for:

WordPress Site URL
WordPress Username
WordPress Application Password (stored in OS keychain)

Available Tools (175)

Content Management (12)

| Tool | Description | |-------------------|------------------------------------------------------------------------------------------------| | wp_list_posts | List posts with pagination, filtering by status/category/tag/author, and search | | wp_get_post | Get a post by ID with full content, meta fields, and taxonomy info | | wp_create_post | Create a post (defaults to draft). Supports HTML, categories, tags, featured image, meta | | wp_update_post | Update any post field. Only provided fields are modified | | wp_delete_post | Move to trash by default. Permanent deletion requires force=true. Confirmation token when WP_CONFIRM_DESTRUCTIVE=true | | wp_search | Full-text search across all content types | | wp_list_pages | List pages with hierarchy (parent/child), templates, and menu order | | wp_get_page | Get page content, template, and hierarchy info | | wp_create_page | Create a page with parent, template, and menu_order support | | wp_update_page | Update any page field | | wp_validate_block_structure | Validate Gutenberg block HTML before saving. Detects unclosed blocks, malformed JSON, invalid nesting, deprecated blocks | | wp_bulk_update | Bulk update content across multiple posts/pages. Supports text replacement, meta updates, status changes, content append. Dry-run by default |

Media Library (3)

| Tool | Description | |-------------------|--------------------------------------------------------------------------| | wp_list_media | Browse media with type filtering (image/video/audio/document) | | wp_get_media | Get URL, dimensions, alt text, caption, and all available sizes | | wp_upload_media | Upload a file from a public URL to the WordPress media library |

Taxonomies & Structure (5)

| Tool | Description | |--------------------------|----------------------------------------------------------------------| | wp_list_categories | List categories with hierarchy, post count, and descriptions | | wp_list_tags | List tags with post count | | wp_create_taxonomy_term| Create a new category or tag | | wp_list_post_types | Discover all registered post types (including custom ones) | | wp_list_custom_posts | List content from any custom post type (products, portfolio, events) |

Engagement (2)

| Tool | Description | |---------------------|--------------------------------------------------------| | wp_list_comments | List comments with filtering by post, status, and author | | wp_create_comment | Create a comment or reply on any post |

Users & Security (10)

New in v4.7.0 — Full user CRUD, role/capability inspection, password reset, and application password management.

| Tool | Description | |-------------------------------------|--------------------------------------------------------------------------------------------| | wp_list_users | List users with roles, search, pagination. Supports full/summary/ids_only modes | | wp_get_user | Full user profile: login, email, role, meta, registration date, avatar | | wp_create_user | Create user with username, email, password, role. Requires confirm=true. Write | | wp_update_user | Update email, display_name, role, bio, meta. Write | | wp_delete_user | Delete user with mandatory post reassignment. Requires confirm=true. Blocked by WP_DISABLE_DELETE | | wp_list_user_roles | All available roles with their capabilities listed | | wp_get_user_capabilities | Active capabilities for a specific user | | wp_reset_user_password | Trigger password reset email. Requires mu-plugin companion. Write | | wp_list_user_application_passwords| List app passwords with name, UUID, created date, last used. Read-only | | wp_revoke_application_password | Revoke an application password by UUID. Write |

SEO Metadata (3)

Auto-detects Yoast, RankMath, SEOPress, AIOSEO.

| Tool | Description | |---------------------|----------------------------------------------------------------------------------------------| | wp_get_seo_meta | Read SEO title, description, focus keyword, canonical, robots, Open Graph | | wp_update_seo_meta| Update SEO metadata with automatic plugin detection | | wp_audit_seo | Bulk audit SEO across posts/pages with quality scoring (0-100) and missing fields detection |

SEO Audit Suite (10) — New in v4.0-v4.2

All read-only, always allowed regardless of governance flags.

| Tool | Description | |-----------------------------------|------------------------------------------------------------------------------------------| | wp_audit_media_seo | Audit media library for missing alt text, short alt text, and unoptimized filenames | | wp_find_orphan_pages | Identify posts with no internal links pointing to them, sorted by word count | | wp_audit_heading_structure | Analyze H1/H2/H3 hierarchy. Detects H1 in body, heading level skips, empty headings | | wp_find_thin_content | Surface posts below configurable word count threshold with quality scoring | | wp_audit_canonicals | Validate canonical URLs. Detects missing, mismatched, cross-domain. Multi-plugin support | | wp_analyze_eeat_signals | E-E-A-T scoring per post (0-100): author bio, dates, citations, structured data | | wp_find_broken_internal_links | HEAD request link checker. Detects 404s, redirects, timeouts. Configurable batch size | | wp_find_keyword_cannibalization | Detect posts sharing the same focus keyword. Groups conflicts, flags weakest | | wp_audit_taxonomies | Taxonomy bloat: unused terms, near-duplicates (Levenshtein), single-post terms | | wp_audit_outbound_links | External link profile: low-authority domains, missing nofollow, broken URLs |

Schema.org Intelligence (7) — New in v4.9

Generation + injection + local validation end-to-end.

| Tool | Description | |----------------------------------|--------------------------------------------------------------------------------------------| | wp_generate_schema_article | Generates Article JSON-LD from post data with _embed for author and featured image | | wp_generate_schema_faq | Detects Q&A from Gutenberg FAQ blocks, RankMath, AIOSEO, <details>, or H3+paragraph | | wp_generate_schema_howto | Detects steps from ordered lists or numbered headings. Extracts totalTime, estimatedCost | | wp_generate_schema_localbusiness| Pulls business data from ACF, Yoast Local SEO, or WP options | | wp_generate_schema_breadcrumb | Rebuilds full breadcrumb hierarchy: Home > Category/Parent > Post | | wp_inject_schema | Injects JSON-LD into _custom_schema_jsonld post meta. Supports dry_run=true. Requires mu-plugin | | wp_validate_schema_live | Fetches live URL, extracts all JSON-LD blocks, validates structure and required fields |

Content Intelligence (16) — New in v4.4

All read-only, always allowed regardless of governance flags.

| Tool | Description | |-------------------------------|------------------------------------------------------------------------------------------| | wp_get_content_brief | Editorial brief aggregator: SEO + structure + links in 1 call | | wp_extract_post_outline | H1-H6 outline extraction with category-level pattern analysis | | wp_audit_readability | Bulk Flesch-Kincaid FR scoring with transition word and passive voice analysis | | wp_audit_update_frequency | Outdated content detection cross-referenced with SEO scores | | wp_build_link_map | Internal link matrix with simplified PageRank scoring (0-100) | | wp_audit_anchor_texts | Anchor text diversity audit: generic, over-optimized, image link detection | | wp_audit_schema_markup | JSON-LD schema.org detection and validation (Article, FAQ, HowTo, LocalBusiness) | | wp_audit_content_structure | Editorial structure scoring (0-100): intro, conclusion, FAQ, TOC, lists, images | | wp_find_duplicate_content | TF-IDF cosine similarity for near-duplicate detection with union-find clustering | | wp_find_content_gaps | Taxonomy under-representation analysis (categories + tags) | | wp_extract_faq_blocks | FAQ inventory: JSON-LD, Gutenberg blocks, HTML patterns | | wp_audit_cta_presence | CTA detection (6 types) with scoring 0-100 | | wp_extract_entities | Regex/heuristic named entity extraction (brands, locations, persons, organizations) | | wp_get_publishing_velocity | Publication cadence by author/category with trend detection | | wp_compare_revisions_diff | Textual diff between revisions with amplitude scoring | | wp_list_posts_by_word_count | Posts sorted by length with 6-tier segmentation |

Editorial Intelligence (6) — New in v4.13

Batch processing up to 500 posts, reuses TF-IDF engine. All read-only.

| Tool | Description | |----------------------------------|------------------------------------------------------------------------------------------| | wp_suggest_content_updates | Finds stale posts needing updates. Prioritizes by age, outdated date references, thin content | | wp_audit_author_consistency | Profiles each author: post count, avg word count, frequency, readability, media usage | | wp_build_editorial_calendar | Analyzes 12 months of history for seasonality, best days, scheduled posts, gaps | | wp_find_pillar_content_gaps | Identifies topics with 3+ posts without a dedicated pillar page | | wp_audit_internal_link_equity | Builds link graph, identifies orphans, over-linked pages, equity distribution 0-100 | | wp_suggest_content_cluster | Clusters content by TF-IDF + cosine similarity around a keyword or post_id seed |

Multilingual Intelligence EU (6) — New in v4.10

WPML · Polylang Pro · Polylang Free (hreflang fallback) · TranslatePress.

| Tool | Description | |-----------------------------------|----------------------------------------------------------------------------------------| | wp_detect_multilingual_plugin | Auto-detects WPML > Polylang Pro > Polylang Free > TranslatePress | | wp_list_languages | Lists configured languages with code, name, locale, URL prefix, flag | | wp_get_post_translations | Gets all translations with post IDs, titles, URLs, statuses, SEO meta per language | | wp_audit_translation_coverage | Coverage percentages, missing counts, top 10 untranslated posts by word count | | wp_find_missing_seo_translations| Finds translated posts missing SEO metadata (title, description, OG) | | wp_sync_seo_meta_translations | Copies SEO meta from source to translations. dry_run=true by default. Write |

Performance & Core Web Vitals (6) — New in v4.9

| Tool | Description | |--------------------------------------|----------------------------------------------------------------------------------------| | wp_audit_page_speed | Google PageSpeed Insights: Core Web Vitals (LCP, CLS, INP, FCP, TTFB), score, opportunities. Requires PAGESPEED_API_KEY | | wp_find_render_blocking_resources | Detects render-blocking <link> and <script> in <head> (excludes defer/async) | | wp_audit_image_optimization | Media library audit: non-WebP, large files (>100KB), missing alt text | | wp_check_caching_status | Detects caching plugins (WP Rocket, W3TC, LiteSpeed) and cache HTTP headers | | wp_audit_database_bloat | Revisions, expired transients, auto-drafts, spam, orphan postmeta. Requires mu-plugin | | wp_get_plugin_performance_impact | Ranks active plugins by estimated performance impact (~50 plugin database) |

Security Audit (6) — New in v4.11

All read-only. Optional WPSCAN_API_KEY for CVE data.

| Tool | Description | |----------------------------------|------------------------------------------------------------------------------------------| | wp_audit_user_security | Audits admin accounts: default usernames, inactive accounts, generic emails, missing 2FA | | wp_check_file_permissions | Checks wp-config.php, .htaccess, uploads/ permissions. Requires mu-plugin | | wp_list_recently_modified_files| Recently modified files with suspicious detection: PHP in uploads, hex filenames | | wp_audit_plugin_vulnerabilities| Scans plugins against WPScan API. CVEs with CVSS scores. Without API key: version list | | wp_check_ssl_certificate | TLS validation (expiry, issuer, SAN), security headers (HSTS, CSP). Grades A+ to F | | wp_audit_login_security | Login security score /100: XML-RPC, user enumeration, 2FA, brute force protection |

Site Health & Diagnostics (8) — New in v4.7

wp_get_debug_log and wp_get_active_hooks require mu-plugin companion.

| Tool | Description | |----------------------------|----------------------------------------------------------------------------------------| | wp_get_site_health_status| Overall health score (good/recommended/critical) with issue counts by severity | | wp_list_site_health_issues| All health issues with label, description, severity, and badge | | wp_get_site_health_info | System info: PHP version, MySQL, memory limit, extensions, WP constants | | wp_get_debug_log | Read last N lines of debug.log filtered by level. Max 500 lines. Requires mu-plugin | | wp_get_cron_events | List all WP-Cron events with hook, schedule, next run, and overdue detection | | wp_get_transients | List database transients with key, expiration, size. Filter by expired/active | | wp_check_php_compatibility| Check each plugin's PHP version requirement vs current PHP | | wp_get_active_hooks | Inventory of registered actions and filters with callbacks and priorities. Requires mu-plugin |

Full Site Editing — FSE (26) — New in v4.6

Templates (5) · Template Parts (5) · Global Styles (3) · Block Patterns (4) · Navigation Menus (5) · Widgets (4)

| Tool | Description | |-----------------------------|--------------------------------------------------------------------------| | wp_list_templates | List all block templates with filtering by post type | | wp_get_template | Get a single block template by ID | | wp_create_template | Create a new block template. Write | | wp_update_template | Update an existing block template. Write | | wp_delete_template | Delete a block template. Blocked by WP_DISABLE_DELETE | | wp_list_template_parts | List template parts with area filtering (header/footer/general) | | wp_get_template_part | Get a single template part by ID | | wp_create_template_part | Create a new template part. Write | | wp_update_template_part | Update an existing template part. Write | | wp_delete_template_part | Delete a template part. Blocked by WP_DISABLE_DELETE | | wp_get_global_styles | Get global styles (colors, typography, spacing) by post ID | | wp_update_global_styles | Update global styles and settings. Write | | wp_get_global_styles_variations | List available style variations for a theme | | wp_list_block_patterns | List all registered block patterns | | wp_get_block_pattern | Get a single block pattern by name | | wp_create_block_pattern | Create a custom block pattern. Write | | wp_delete_block_pattern | Delete a custom block pattern. Blocked by WP_DISABLE_DELETE | | wp_list_navigation_menus | List navigation menus with search and status filtering | | wp_get_navigation_menu | Get a single navigation menu with block content | | wp_create_navigation_menu | Create a navigation menu. Write | | wp_update_navigation_menu | Update a navigation menu. Write | | wp_delete_navigation_menu | Delete a navigation menu. Blocked by WP_DISABLE_DELETE | | wp_list_widgets | List all widgets with sidebar filtering | | wp_get_widget | Get a single widget with instance settings and rendered output | | wp_update_widget | Update widget settings or move to another sidebar. Write | | wp_delete_widget | Delete a widget. Blocked by WP_DISABLE_DELETE |

Plugin Intelligence Layer (up to 7) — New in v4.5-v4.6

Activates only when plugin detected via REST namespace discovery. Disable all: WP_DISABLE_PLUGIN_LAYERS=true

ACF (Advanced Custom Fields) — requires /acf/v3 namespace

| Tool | Description | |----------------------|--------------------------------------------------------------------------| | acf_get_fields | Get ACF custom fields for a post/page with key filtering and raw/compact/summary modes | | acf_list_field_groups | List all configured ACF field groups | | acf_get_field_group| Get full detail of an ACF field group by ID | | acf_update_fields | Update ACF custom fields. Write — blocked by WP_READ_ONLY |

Elementor — requires /elementor/v1 namespace

| Tool | Description | |-----------------------------|------------------------------------------------------------------------| | elementor_list_templates | List Elementor templates (page, section, block, popup) | | elementor_get_template | Get full template content and elements. Context-guarded at 50k chars | | elementor_get_page_data | Elementor editor data: widgets used, elements count |

Plugin Intelligence (6) — New in v4.5

Requires WP_ENABLE_PLUGIN_INTELLIGENCE=true. Read-only (except write modes noted).

| Tool | Description | |---------------------------|------------------------------------------------------------------------------------------| | wp_get_rendered_head | Fetch real <head> HTML via RankMath/Yoast headless endpoint. Compare rendered vs stored | | wp_audit_rendered_seo | Bulk rendered-vs-stored SEO divergence detection with per-post scoring | | wp_get_pillar_content | Read or set RankMath cornerstone/pillar flag. Write blocked by WP_READ_ONLY | | wp_audit_schema_plugins | Validate JSON-LD from SEO plugin native fields (rank_math_schema or yoast_head_json) | | wp_get_seo_score | Read RankMath native SEO score (0-100) with bulk mode distribution stats | | wp_get_twitter_meta | Read/write Twitter Card meta for RankMath, Yoast, SEOPress. Write blocked by WP_READ_ONLY |

Plugins & Themes (5)

| Tool | Description | |-----------------------|--------------------------------------------------------------------------------------| | wp_list_plugins | List installed plugins with status, version, author. Requires activate_plugins | | wp_activate_plugin | Activate a plugin. Blocked by WP_READ_ONLY and WP_DISABLE_PLUGIN_MANAGEMENT | | wp_deactivate_plugin| Deactivate a plugin. Blocked by WP_READ_ONLY and WP_DISABLE_PLUGIN_MANAGEMENT | | wp_list_themes | List installed themes with active theme detection | | wp_get_theme | Get theme details by stylesheet slug |

Revisions (4)

| Tool | Description | |----------------------|------------------------------------------------------------------------------------------| | wp_list_revisions | List revisions of a post or page (metadata only) | | wp_get_revision | Get a specific revision with full content | | wp_restore_revision| Restore a post to a previous revision | | wp_delete_revision | Permanently delete a revision. Blocked by WP_READ_ONLY, WP_DISABLE_DELETE, WP_CONFIRM_DESTRUCTIVE |

Editorial Workflow & Visual Staging (9) — v3.2 / v4.15 / v5.1

Requires WP_REQUIRE_APPROVAL=true.

| Tool | Description | |------------------------|--------------------------------------------------------------------------| | wp_submit_for_review | Transition a draft post to pending status (author action) | | wp_approve_post | Transition a pending post to publish (editor/admin action) | | wp_reject_post | Return a pending post to draft with a mandatory rejection reason |

Visual Staging (5) — New in v4.15. Requires WP_VISUAL_STAGING=true for interception.

| Tool | Description | |------|-------------| | wp_create_staging_draft | Clone a published page/post into a shadow draft for safe editing | | wp_list_staging_drafts | List all pending staging drafts, optionally filtered by source | | wp_get_staging_preview_url | Get native WordPress preview URL for a staging draft | | wp_merge_staging_to_live | Merge validated staging draft content to the live page (two-step) | | wp_discard_staging_draft | Permanently delete a staging draft without touching the live page |

Workflow Orchestrator (1) — New in v5.1.

| Tool | Description | |------|-------------| | wp_run_workflow | Execute named or custom tool sequences in a single call. Built-in: seo_audit_and_stage, site_health_report, content_publish_safe, wc_product_audit |

Internal Link Intelligence (2) — New in v3.3

| Tool | Description | |-----------------------------|----------------------------------------------------------------------------------------| | wp_analyze_links | Audit all internal/external links in a post. HEAD verification per link | | wp_suggest_internal_links | Semantic link suggestions scored by category, freshness, SEO keyword, title match |

WooCommerce Core (6) — New in v3.4

Requires WC_CONSUMER_KEY and WC_CONSUMER_SECRET.

| Tool | Description | |---------------------|--------------------------------------------------------------------------------------| | wc_list_products | List products with filtering by status, category, search, and sorting | | wc_get_product | Get product by ID with full details and variations summary | | wc_list_orders | List orders with filtering by status, customer, and date | | wc_get_order | Get order by ID with line items, shipping, billing, and payment details | | wc_list_customers | List customers with search and role filtering | | wc_price_guardrail| Analyze a price change for safety (read-only). Returns safe/unsafe |

WooCommerce Intelligence (4) — New in v3.5

| Tool | Description | |---------------------------|------------------------------------------------------------------------------------| | wc_inventory_alert | Identify low-stock and out-of-stock products below threshold, sorted by urgency | | wc_order_intelligence | Customer purchase history: lifetime value, average order, favourite products | | wc_seo_product_audit | Audit product listings for SEO issues (descriptions, images, alt text, slugs) | | wc_suggest_product_links| Suggest WooCommerce products to link from blog posts based on keyword relevance |

WooCommerce Advanced Intelligence (7) — New in v4.12

All read-only.

| Tool | Description | |-------------------------------------|------------------------------------------------------------------------------------| | wc_audit_product_seo | Product SEO score /100: title, description, slug, image alt, schema presence | | wc_find_abandoned_carts_pattern | Abandoned cart patterns: hourly/daily trends, top products, revenue loss | | wc_audit_checkout_friction | Checkout friction score 0-10: guest checkout, required fields, coupon, multi-step | | wc_get_product_performance | Product metrics with trend comparison: units sold, revenue, refund rate | | wc_audit_stock_alerts | Out-of-stock and low-stock audit with last sale dates. Includes variations | | wc_find_duplicate_products | Duplicates by SKU, title/slug Levenshtein similarity. Union-find grouping | | wc_audit_pricing_consistency | Pricing errors: sale >= regular, zero sale, minimal discounts, expired sales |

WooCommerce Write (3) — New in v3.6

All blocked by WP_READ_ONLY.

| Tool | Description | |-----------------------|--------------------------------------------------------------------------------------| | wc_update_product | Update product fields. Subject to wc_price_guardrail threshold enforcement | | wc_update_stock | Update stock quantity of a product or variation | | wc_update_order_status| Transition order status (e.g., processing → completed) |

Operations (3)

| Tool | Description | |------------------------|--------------------------------------------------------------------------------------| | wp_set_target | Switch active WordPress site in multi-target mode | | wp_site_info | Site info, current user, post types, enterprise controls, tool_categories, plugin_layer | | wp_get_site_options | Read WordPress site settings (title, tagline, language, timezone) via /wp/v2/settings |

Enterprise Controls

Configure execution policy via environment variables. All restrictions are enforced before any API call is made.

| Control | Default | Effect | |--------------------------------|-------------|--------------------------------------------------------------------------------| | WP_READ_ONLY | false | Blocks all write operations | | WP_DRAFT_ONLY | false | Restricts to draft and pending statuses only | | WP_DISABLE_DELETE | false | Blocks all delete operations | | WP_DISABLE_PLUGIN_MANAGEMENT | false | Blocks plugin activate/deactivate (list still allowed) | | WP_REQUIRE_APPROVAL | false | Blocks direct publish. Forces draft → pending → publish workflow | | WP_CONFIRM_DESTRUCTIVE | false | Requires token confirmation before delete operations | | WP_VISUAL_STAGING | false | When true, direct edits to published pages are intercepted. AI must use staging workflow: wp_create_staging_draft → edit draft → wp_merge_staging_to_live | | WP_VALIDATE_BLOCKS | false | When true, auto-validates Gutenberg block structure on wp_update_post/wp_update_page. Blocks update if errors found | | WP_ALLOWED_TYPES | all | Restricts to specific post types (e.g., post,page) | | WP_ALLOWED_STATUSES | all | Restricts to specific statuses (e.g., draft,pending) | | WP_MAX_CALLS_PER_MINUTE | unlimited | Client-side rate limiting | | WP_AUDIT_LOG | on | Structured JSON audit trail | | WP_COMPACT_JSON | true | Compact JSON output (~30% token reduction). false for debugging | | WP_TOOL_CATEGORIES | (none) | Comma-separated categories to expose. Empty = all 173 tools. Always includes core. Categories: content · media · taxonomy · engagement · users · seo · schema · intelligence · editorial · fse · plugins · workflow · links · woocommerce · security · performance · health | | PAGESPEED_API_KEY | (none) | Google PageSpeed Insights API key. Optional — wp_audit_page_speed degrades gracefully | | WPSCAN_API_KEY | (none) | WPScan vulnerability database API key. Optional — free at wpscan.com/register |

Destructive confirmation flow

When WP_CONFIRM_DESTRUCTIVE=true, wp_delete_post and wp_delete_revision return a stateless confirmation token on the first call instead of executing. The token is valid for 60 seconds (SHA-256, zero persistence). Pass the token back on a second call to confirm execution.

Governance priority order: WP_READ_ONLY → WP_DISABLE_DELETE → WP_CONFIRM_DESTRUCTIVE

Deployment profiles

Agency content production — writers can create and edit, but never publish or delete:

WP_DRAFT_ONLY=true
WP_DISABLE_DELETE=true
WP_ALLOWED_STATUSES=draft,pending
WP_MAX_CALLS_PER_MINUTE=30

Editorial review workflow — forces human approval before publication:

WP_REQUIRE_APPROVAL=true
WP_DISABLE_DELETE=true
WP_AUDIT_LOG=on

Compliance monitoring — read-only access for auditing existing content:

WP_READ_ONLY=true
WP_AUDIT_LOG=on

Regulated publishing — restrict to specific content types in a controlled environment:

WP_ALLOWED_TYPES=post
WP_ALLOWED_STATUSES=draft,pending,publish
WP_DISABLE_DELETE=true
WP_AUDIT_LOG=on

Locked infrastructure — content operations allowed, but no plugin/theme changes:

WP_DISABLE_PLUGIN_MANAGEMENT=true
WP_DISABLE_DELETE=true

E-commerce safe mode — WooCommerce read and intelligence, no writes:

WP_READ_ONLY=true
WC_CONSUMER_KEY=ck_xxx
WC_CONSUMER_SECRET=cs_xxx

Maximum safety — all governance layers active:

WP_READ_ONLY=false
WP_REQUIRE_APPROVAL=true
WP_CONFIRM_DESTRUCTIVE=true
WP_VISUAL_STAGING=true
WP_VALIDATE_BLOCKS=true

Context optimization profiles

Reduce ListTools from ~20k tokens to ~4-9k tokens by loading only the categories you need:

# SEO Agency — content + SEO focus (~32 tools, ~5k tokens)
WP_TOOL_CATEGORIES=seo,content,schema,editorial,intelligence

# E-commerce — WooCommerce focus (~40 tools, ~7k tokens)
WP_TOOL_CATEGORIES=woocommerce,seo,performance,content

# Content team — writing focus (~30 tools, ~5k tokens)
WP_TOOL_CATEGORIES=content,editorial,media,engagement,intelligence

# DevOps / Security audit (~25 tools, ~4k tokens)
WP_TOOL_CATEGORIES=security,health,performance,plugins

# Developer — FSE + plugins (~40 tools, ~7k tokens)
WP_TOOL_CATEGORIES=fse,plugins,content,users

# Full agency mode — all tools (default)
# WP_TOOL_CATEGORIES= (empty or unset)

Blocked actions return a clear error message explaining which control prevented execution, and are logged in the audit trail with status blocked.

MU-Plugin Companion

Some tools require the optional MCP Diagnostics companion mu-plugin to access data not available via the WordPress REST API.

Installation

cp companion/mcp-diagnostics.php /path/to/wp-content/mu-plugins/

Exposed endpoints

Diagnostics — require manage_options

| Endpoint | Method | Description | |---------------------------------------------|--------|------------------------------------------| | /mcp-diagnostics/v1/debug-log | GET | Last N lines of debug.log by level | | /mcp-diagnostics/v1/cron-events | GET | All scheduled WP-Cron events | | /mcp-diagnostics/v1/transients | GET | Database transients with expiration/size | | /mcp-diagnostics/v1/hooks | GET | Registered actions and filters |

Security — require manage_options

| Endpoint | Method | Description | |---------------------------------------------|--------|------------------------------------------| | /mcp-diagnostics/v1/user-activity | GET | Admin last login timestamps | | /mcp-diagnostics/v1/file-permissions | GET | Critical file permission checks | | /mcp-diagnostics/v1/modified-files | GET | Recently modified file listing |

Performance — requires manage_options

WooCommerce — requires manage_options

Schema — requires edit_posts

| Endpoint | Method | Description | |---------------------------------------------|--------|------------------------------------------| | /mcp-diagnostics/v1/schema/{post_id} | GET | Read _custom_schema_jsonld meta | | /mcp-diagnostics/v1/schema/{post_id} | POST | Write schema meta. Blocked by WP_READ_ONLY | | /mcp-diagnostics/v1/schema/{post_id} | DELETE | Remove schema meta. Blocked by WP_READ_ONLY |

Polylang Free — public (no auth required)

| Endpoint | Method | Description | |------------------------------------------------------|--------|----------------------------------| | /mcp-diagnostics/v1/polylang/languages | GET | Polylang languages list | | /mcp-diagnostics/v1/polylang/translations/{post_id}| GET | Post translations by language |

Users — requires manage_options

All endpoints require manage_options capability (Administrator) unless noted. No endpoint modifies data except POST /schema/{post_id} and POST /password-reset — both blocked when WP_READ_ONLY=true.

SEO Metadata

The SEO tools auto-detect which SEO plugin is installed on your WordPress site and use the correct meta fields automatically.

Supported plugins:

Yoast SEO — _yoast_wpseo_title, _yoast_wpseo_metadesc, _yoast_wpseo_focuskw, plus yoast_head_json REST API extension
RankMath — rank_math_title, rank_math_description, rank_math_focus_keyword
SEOPress — _seopress_titles_title, _seopress_titles_desc, _seopress_analysis_target_kw
All in One SEO — _aioseo_title, _aioseo_description, _aioseo_keywords

SEO Audit Scoring

wp_audit_seo scores each post on a 100-point scale:

| Check | Penalty | |--------------------------------------------------------------|---------| | Missing SEO title | -30 | | SEO title too short (< 30 chars) or too long (> 60 chars) | -10 | | Missing meta description | -30 | | Meta description too short (< 120 chars) or too long (> 160 chars) | -10 | | Missing focus keyword | -20 | | Focus keyword not in SEO title | -10 |

Exposing SEO Meta Fields (Required)

Most SEO plugins store their data in WordPress post meta fields that are not exposed via the REST API by default. Without this step, wp_get_seo_meta and wp_audit_seo will return empty results even though your SEO data exists in the database.

Add the following code to your theme's functions.php (Appearance → Theme File Editor → functions.php) or — preferably — create a custom mini-plugin (see below).

Important: When pasting code into functions.php, make sure the file starts with exactly <?php — no extra characters before it. A stray character (like <<?php) will break the WordPress REST API by injecting invalid output before JSON responses, causing Unexpected token '<' errors in MCP.

RankMath:

add_action( 'init', function() {
    $fields = array(
        'rank_math_title',
        'rank_math_description',
        'rank_math_focus_keyword',
        'rank_math_canonical_url',
        'rank_math_robots',
        'rank_math_facebook_title',
        'rank_math_facebook_description',
        'rank_math_facebook_image',
    );
    foreach ( $fields as $field ) {
        foreach ( array( 'post', 'page' ) as $post_type ) {
            register_post_meta( $post_type, $field, array(
                'show_in_rest'  => true,
                'single'        => true,
                'type'          => 'string',
                'auth_callback' => function() {
                    return current_user_can( 'edit_posts' );
                },
            ) );
        }
    }
} );

Yoast SEO:

add_action( 'init', function() {
    $fields = array(
        '_yoast_wpseo_title',
        '_yoast_wpseo_metadesc',
        '_yoast_wpseo_focuskw',
        '_yoast_wpseo_canonical',
        '_yoast_wpseo_meta-robots-noindex',
        '_yoast_wpseo_meta-robots-nofollow',
        '_yoast_wpseo_opengraph-title',
        '_yoast_wpseo_opengraph-description',
        '_yoast_wpseo_opengraph-image',
    );
    foreach ( $fields as $field ) {
        foreach ( array( 'post', 'page' ) as $post_type ) {
            register_post_meta( $post_type, $field, array(
                'show_in_rest'  => true,
                'single'        => true,
                'type'          => 'string',
                'auth_callback' => function() {
                    return current_user_can( 'edit_posts' );
                },
            ) );
        }
    }
} );

SEOPress:

add_action( 'init', function() {
    $fields = array(
        '_seopress_titles_title',
        '_seopress_titles_desc',
        '_seopress_analysis_target_kw',
        '_seopress_robots_canonical',
        '_seopress_robots_index',
        '_seopress_social_fb_title',
        '_seopress_social_fb_desc',
        '_seopress_social_fb_img',
    );
    foreach ( $fields as $field ) {
        foreach ( array( 'post', 'page' ) as $post_type ) {
            register_post_meta( $post_type, $field, array(
                'show_in_rest'  => true,
                'single'        => true,
                'type'          => 'string',
                'auth_callback' => function() {
                    return current_user_can( 'edit_posts' );
                },
            ) );
        }
    }
} );

All in One SEO:

add_action( 'init', function() {
    $fields = array(
        '_aioseo_title',
        '_aioseo_description',
        '_aioseo_keywords',
        '_aioseo_og_title',
        '_aioseo_og_description',
        '_aioseo_og_image_url',
    );
    foreach ( $fields as $field ) {
        foreach ( array( 'post', 'page' ) as $post_type ) {
            register_post_meta( $post_type, $field, array(
                'show_in_rest'  => true,
                'single'        => true,
                'type'          => 'string',
                'auth_callback' => function() {
                    return current_user_can( 'edit_posts' );
                },
            ) );
        }
    }
} );

Alternative: MCP SEO Bridge Plugin (Recommended)

Note: Core content operations require no WordPress plugin. SEO metadata tools may require exposing meta fields via the REST API using either a theme snippet or this optional micro-plugin.

Instead of modifying your theme's functions.php (which gets overwritten on theme updates), create a standalone micro-plugin.

Create the file wp-content/plugins/mcp-seo-bridge.php:

<?php
/**
 * Plugin Name: MCP SEO Bridge
 * Description: Exposes SEO plugin meta fields via REST API for WordPress MCP Server
 * Version: 1.0.0
 * Author: AdSim
 * Author URI: https://adsim.be
 */

if ( ! defined( 'ABSPATH' ) ) exit;

add_action( 'init', function() {
    $fields = array();

    if ( defined( 'RANK_MATH_VERSION' ) ) {
        $fields = array(
            'rank_math_title', 'rank_math_description', 'rank_math_focus_keyword',
            'rank_math_canonical_url', 'rank_math_robots',
            'rank_math_facebook_title', 'rank_math_facebook_description', 'rank_math_facebook_image',
        );
    } elseif ( defined( 'WPSEO_VERSION' ) ) {
        $fields = array(
            '_yoast_wpseo_title', '_yoast_wpseo_metadesc', '_yoast_wpseo_focuskw',
            '_yoast_wpseo_canonical', '_yoast_wpseo_meta-robots-noindex', '_yoast_wpseo_meta-robots-nofollow',
            '_yoast_wpseo_opengraph-title', '_yoast_wpseo_opengraph-description', '_yoast_wpseo_opengraph-image',
        );
    } elseif ( defined( 'SEOPRESS_VERSION' ) ) {
        $fields = array(
            '_seopress_titles_title', '_seopress_titles_desc', '_seopress_analysis_target_kw',
            '_seopress_robots_canonical', '_seopress_robots_index',
            '_seopress_social_fb_title', '_seopress_social_fb_desc', '_seopress_social_fb_img',
        );
    } elseif ( defined( 'AIOSEO_VERSION' ) ) {
        $fields = array(
            '_aioseo_title', '_aioseo_description', '_aioseo_keywords',
            '_aioseo_og_title', '_aioseo_og_description', '_aioseo_og_image_url',
        );
    }

    foreach ( $fields as $field ) {
        foreach ( array( 'post', 'page' ) as $post_type ) {
            register_post_meta( $post_type, $field, array(
                'show_in_rest'  => true,
                'single'        => true,
                'type'          => 'string',
                'auth_callback' => function() {
                    return current_user_can( 'edit_posts' );
                },
            ) );
        }
    }
} );

Activate it from WordPress Admin → Plugins. This approach auto-detects your SEO plugin and survives theme updates.

Verifying SEO Fields Are Exposed

After adding the code, verify the fields are accessible:

curl -s -u "username:application-password" \
  "https://yoursite.com/wp-json/wp/v2/posts?per_page=1" | python3 -m json.tool | grep -E "rank_math|yoast|seopress|aioseo"

If you see your SEO fields in the meta object, the configuration is working.

Troubleshooting SEO Fields

| Symptom | Cause | Fix | |--------------------------------------|------------------------------------------|-------------------------------------------------| | wp_audit_seo returns empty SEO data | Meta fields not exposed via REST API | Add register_post_meta() code above | | Unexpected token '<' on all calls | Stray character before <?php | Remove any characters before <?php | | SEO fields visible but all null | SEO plugin not yet configured on posts | Set titles/descriptions in RankMath/Yoast editor| | No SEO plugin detected | Plugin constant not matched | Verify your SEO plugin is active | | Fields lost after theme update | Code was in functions.php | Use the MCP SEO Bridge plugin instead |

WooCommerce Setup

Generate API Keys

Go to WooCommerce → Settings → Advanced → REST API → Add key.

Set permissions to Read/Write if you plan to use wc_update_product or wc_update_order_status. Set to Read for a read-only WooCommerce integration.

WC_CONSUMER_KEY=ck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
WC_CONSUMER_SECRET=cs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Price Guardrail

wc_price_guardrail analyzes proposed price changes before any write operation. It returns safe or unsafe based on a configurable threshold (default 20%). Claude should call this tool before wc_update_product when modifying prices.

WC_PRICE_GUARDRAIL_THRESHOLD=20   # percentage — changes above this require explicit override

wc_price_guardrail is always allowed regardless of WP_READ_ONLY. It never modifies data.

Testing

57 test files · 1061 unit tests covering all 173 tools — zero network calls, fully mocked.

npm test              # run all tests (vitest)
npm run test:watch    # watch mode
npm run test:coverage # coverage report

| Test file |--------------------------------- | governance.test.js | posts.test.js | pages.test.js | media.test.js | taxonomies.test.js | comments.test.js | users.test.js | users.crud.test.js | search.test.js | seo.test.js | plugins.test.js | themes.test.js | revisions.test.js | editorial.test.js | links.test.js | woocommerce.test.js | woocommerce.advanced.test.js | auditMediaSeo.test.js | findOrphanPages.test.js | auditHeadingStructure.test.js | findThinContent.test.js | auditCanonicals.test.js | analyzeEeatSignals.test.js | findBrokenInternalLinks.test.js| | findKeywordCannibalization | auditTaxonomies.test.js | auditOutboundLinks.test.js | contentAnalyzer.test.js | contentIntelligence.test.js | pluginIntelligence.test.js | editorialIntelligence.test.js | fse.test.js | diagnostics.test.js | performance.test.js | schema.test.js | multilingual.test.js | security.test.js | dynamicFiltering.test.js | outputCompression.test.js | site.test.js | Scope | Tests | -|------------------------------------------------------------------------------------------------|-------| | All governance flags + combinations including WP_REQUIRE_APPROVAL and WP_CONFIRM_DESTRUCTIVE | 30 | | list, get, create, update, delete, search | 18 | | list, get, create, update | 12 | | list, get, upload | 14 | | categories, tags, create term | 16 | | list, create | 12 | | list | 7 | | get, create, update, delete, roles, capabilities, password reset, app passwords | — | | search, post types, custom posts | 10 | | get, update, audit | 12 | | list, activate, deactivate | 16 | | list, get | 8 | | list, get, restore, delete | 17 | | submit_for_review, approve, reject | 15 | | analyze_links, suggest_internal_links | 16 | | products, orders, customers, write, guardrail | 40 | | product SEO, abandoned carts, checkout friction, performance, stock, duplicates, pricing | 37 | | media alt text audit, filename scoring | 12 | | inbound link detection, exclusion list | 10 | | H1/H2/H3 hierarchy, level skips, keyword detection | 12 | | word count threshold, heading density | 10 | | canonical validation, mismatch detection, multi-plugin | 12 | | E-E-A-T scoring, author bio, citations, structured data | 12 | HEAD request batching, 4xx/3xx detection | 12 | .test.js | focus keyword conflicts, multi-plugin detection | 10 | | Levenshtein duplicates, unused terms, over-tagging | 12 | | external link profile, nofollow detection | 10 | | readability, TF-IDF, cosine similarity, entities, text diff | 44 | | 16 content intelligence tools | 125 | | 6 plugin intelligence tools | 48 | | 6 editorial intelligence tools | 37 | | FSE templates, template parts, global styles, patterns, navigation, widgets | — | | Site health, debug log, cron, transients, PHP compat, hooks | — | | Page speed, render blocking, image optimization, caching, database bloat, plugin impact | — | | Schema generation, injection, live validation | — | | Plugin detection, languages, translations, coverage, SEO translations | — | | User security, file permissions, modified files, vulnerabilities, SSL, login security | 37 | | WooCommerce/editorial/plugin-intelligence/category filtering, combined counts | 19 | | mode=full/summary/ids_only for 10 listing tools | 30 | | site info, set target