mcp-wordpress

Model Context Protocol server for WordPress — content, SEO and marketing automation

A Model Context Protocol server that gives Claude (or any MCP-compatible LLM) direct access to a self-hosted WordPress site over its REST API.

Status: v1.0.0 release candidate — all 33 tools implemented, 264 tests, full release pipeline ready.

v1.0 — what works today

System

• wp_health_check — verify connectivity, detect REST namespaces, detect MCP Bridge and SEO plugins

Posts (full CRUD)

• wp_posts_list — list with filters (status, search, author, categories, tags, date range, ordering, pagination)

• wp_posts_get — fetch a single post by id with full content

• wp_posts_create — create a draft (default) or any status (publish/future/private require publish tier)

• wp_posts_update — partial update by id

• wp_posts_publish — shortcut to set status=publish

• wp_posts_schedule — schedule for future publication (date must be in the future)

• wp_posts_delete — to trash by default; force+confirm for hard delete (MODE=full)

• wp_posts_get_revisions — list revisions/autosaves of a post

Pages (full CRUD)

• wp_pages_list — list with filters (parent for hierarchy, status, search, author, ordering)

• wp_pages_get — fetch a single page by id with full content

• wp_pages_create — create with hierarchy (parent) and ordering (menu_order)

• wp_pages_update — partial update including re-parenting

• wp_pages_delete — to trash by default; force+confirm for hard delete

Media (full CRUD)

• wp_media_list — list with filters (media_type, mime_type, search, date range, parent post)

• wp_media_upload — upload from URL or base64; optional title/alt_text/caption/description; max 25 MB

• wp_media_set_alt_text — update alt_text + caption + description for accessibility and SEO

• wp_media_delete — to trash by default; force+confirm for hard delete

Taxonomies

• wp_taxonomies_list_categories — list with search, parent (hierarchy), hide_empty, ordering

• wp_taxonomies_create_category — create with optional parent

• wp_taxonomies_list_tags — list flat tags with post counts

• wp_taxonomies_create_tag — create a tag

• wp_taxonomies_assign_to_post — replace categories and/or tags on a post

Search

• wp_search_posts — full-text search via /wp/v2/search across posts, pages, CPTs, and terms

SEO meta

• wp_seo_detect_provider — detect active provider (bridge / yoast / rankmath / null) and its capabilities

• wp_seo_get_meta — read SEO meta for a post via the active provider

• wp_seo_set_meta — write SEO meta (title, description, OG, Twitter, canonical, robots, JSON-LD, focus_keyword) via the active provider

• wp_seo_analyze_post — readability (Flesch-Kincaid ES/EN/PT) + keyword density + headings hierarchy lint + length stats; optional focus_keyword for presence check

• wp_seo_suggest_internal_links — ranked related-post suggestions from a keyword or post_id; title matches weighted 3x over excerpt + recency boost

Bulk operations (MODE=full)

• wp_bulk_find_replace — find/replace literal substring across post content. Dry-run by default; apply with confirm token.

• wp_bulk_update_seo — apply same SEO meta to many posts via active provider. Dry-run by default; apply with confirm token.

Both bulk tools require MODE=full (set MODE=full env var). The dry-run response includes the exact confirm_token you need to pass to actually apply the change.

System

• wp_health_check (covered earlier) — REST namespaces + bridge + SEO plugin detection

• wp_get_site_info — title, tagline, URL, language, timezone, sitemap URL, posts-per-page

• wp_detect_page_builder — warn when Elementor/Divi/Beaver/WPBakery is active (their content can't be edited via posts tools)

Related MCP server: WordPress Standalone MCP Server

Architecture

• TypeScript / Node ≥22, ESM modules

• @modelcontextprotocol/sdk over stdio transport

• Application Password authentication (native since WP 5.6)

• Rate limiting (Bottleneck), retry with exponential backoff, in-memory LRU+TTL cache

• Three operational modes: read-only / safe (default) / full

• Audit log of all write operations

See docs/superpowers/specs/2026-06-01-mcp-wordpress-design.md for the full design.

Installation

npm install -g @iamsamuelfraga/mcp-wordpress

Or via npx (no installation):

npx -y @iamsamuelfraga/mcp-wordpress

Setup

1. Create an Application Password in WordPress

Go to WP Admin → Users → Your Profile → Application Passwords. Enter a name (e.g., "Claude MCP") and click "Add New Application Password". Copy the 24-character password (formatted as 6 groups of 4 characters).

2. Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "@iamsamuelfraga/mcp-wordpress"],
      "env": {
        "WP_URL": "https://your-site.com",
        "WP_USER": "your_admin_username",
        "WP_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx",
        "MODE": "safe"
      }
    }
  }
}

Restart Claude Desktop.

3. Verify

In Claude, ask: "Run a health check on my WordPress site." — you should see your site title, the detected REST namespaces, and whether SEO plugins are present.

Companion plugin (optional but recommended)

For full SEO functionality (rendering meta description, Open Graph, Twitter Card, JSON-LD, and per-post robots directives in your site's <head>), install the MCP WordPress Bridge companion plugin on your WordPress site.

Install via GitHub Releases

1. Download mcp-wordpress-bridge-X.Y.Z.zip from the Releases page.

2. In wp-admin, go to Plugins → Add New → Upload Plugin → choose the zip → Install → Activate.

3. No further configuration needed. The plugin auto-detects Yoast / Rank Math / AIOSEO / SEOPress and defaults to coexist mode (no double-rendering).

Mode constants (optional, in wp-config.php)

define('MCP_BRIDGE_MODE', 'coexist'); // default: skip if another SEO plugin is active
// define('MCP_BRIDGE_MODE', 'override'); // always render our meta
// define('MCP_BRIDGE_MODE', 'disable');  // don't render anything (data layer only)

What the plugin exposes

Once installed, the MCP server detects the bridge via wp_health_check (look for bridge.installed: true). New REST endpoints become available under /wp-json/mcp/v1/*:

• GET /info — plugin version, capabilities, detected SEO plugins

• GET|POST|DELETE /seo/{post_id} — read/write/clear our SEO meta for a post

• GET /plugins — active plugins list

• GET /theme — active theme info

• GET /permalinks — read-only permalink structure

• GET /health — health check (no auth)

Configuration

All settings via environment variables:

Development

git clone https://github.com/iamsamuelfraga/mcp-wordpress.git
cd mcp-wordpress
npm install
npm run build
npm test

Integration tests (Docker)

# 1. Start the Dockerized WordPress
docker compose -f docker-compose.test.yml up -d

# 2. Seed WP and capture an Application Password (printed on stdout)
APP_PASSWORD=$(./tests/integration/wp-seed.sh)

# 3. Run integration tests
WP_URL=http://localhost:8080 \
WP_USER=admin \
WP_APP_PASSWORD="$APP_PASSWORD" \
npm run test:integration

# 4. Tear down
docker compose -f docker-compose.test.yml down -v

Releases

This project uses semantic-release to automate versioning, changelog generation, and publishing. Every push to main runs the release workflow:

• Inspects commits using Conventional Commits (feat:, fix:, chore:, docs:, refactor:, etc.).

• Bumps the version accordingly (patch / minor / major).

• Updates CHANGELOG.md.

• Publishes to npm as @iamsamuelfraga/mcp-wordpress.

• Creates a GitHub Release with the companion plugin .zip attached.

To enable npm publishing, the repository owner must add an NPM_TOKEN secret in GitHub repo settings.

License

MIT © 2026 Samuel Fraga