mcp-for-page-builders
A high-performance MCP (Model Context Protocol) server for WordPress page builders — written in Rust.
5.4MB binary · ~3MB RAM · ~1ms startup · 75 tools
Purpose
This project provides AI assistants with deep, structured access to WordPress page builders through the Model Context Protocol. Rather than treating WordPress pages as opaque HTML blobs, it exposes the underlying page builder data model — allowing AI tools to read, create, and modify content at the element level with full awareness of widget types, settings schemas, and design tokens.
Current State: Elementor
At present, the server is purpose-built for Elementor — the most widely used WordPress page builder. It integrates directly with Elementor's native REST API (elementor/v1/*) rather than the generic WordPress REST API, giving it access to element trees, widget schemas, global design tokens, experiments, and the live editor via Chrome DevTools Protocol.
Key capabilities in the current Elementor implementation:
- Element-level CRUD — add, update, move, duplicate, or remove individual widgets without replacing the entire page
- Widget schema validation with "did you mean?" suggestions for incorrect setting keys
- Global design token management (colors, typography)
- Elementor kit settings, feature flags, and CSS cache control
- Theme Builder template creation with automatic condition activation
- Visual tools — screenshots with inline images, side-by-side stitched comparison, CDP-based DOM inspection
- CSS-to-Elementor mapping — convert computed styles to Elementor widget settings
- One-shot visual parity —
match_stylesextracts CSS from a reference, converts, and applies in one call - Live editor control via CDP — open editor, select widgets, change settings, save
- Custom widget scaffolding — generate and deploy PHP widget classes via a companion bridge plugin
- Local environment detection — auto-detect and boot DDEV/Lando projects
- Page interaction before capture —
pre_json all visual tools to click menus, dismiss banners, etc.
Future Direction: Universal Page Builder Support
The long-term vision is to make this server the single MCP integration point for any WordPress page builder. When a request comes in, the server will:
- Detect which page builder(s) are active on the WordPress installation (Elementor, Beaver Builder, Bricks, Divi, Gutenberg blocks, etc.)
- Automatically route requests to the appropriate handler for that builder
- Expose a unified tool interface regardless of which builder is installed — so AI assistants don't need to know or care which builder is in use
This means a single MCP configuration will work across different WordPress sites regardless of their page builder choice, and AI tools will be able to work with any builder's data model through a consistent API.
Quick Start
# Build from source
git clone https://github.com/juslintek/mcp-for-page-builders
cd mcp-for-page-builders
cargo build --release
Add to your MCP client config (e.g. .kiro/settings/mcp.json, claude_desktop_config.json):
{
"mcpServers": {
"mcp-for-page-builders": {
"command": "/path/to/mcp-for-page-builders"
}
}
}
Then connect to a WordPress site:
Use the `authenticate` tool with wp_url "https://your-site.com"
This opens a browser for WordPress Application Password approval — no credentials in config files. Credentials are stored internally in ~/.config/mcp-for-page-builders/.
Multi-Site Support
Connect multiple sites. Switch between them without restarting:
Use `connect_site` to add a site, or `switch_site` to change the active site.
Legacy: Environment Variables
You can still pass credentials via environment variables if preferred:
{
"mcpServers": {
"mcp-for-page-builders": {
"command": "/path/to/mcp-for-page-builders",
"env": {
"WP_URL": "https://your-site.com",
"WP_APP_USER": "admin",
"WP_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
}
}
}
}
CDP-Only Mode
WordPress credentials are optional. Without WP_URL, the server starts in CDP-only mode — all visual and schema tools work, WordPress-dependent tools return a helpful error pointing to setup_wizard.
{
"mcpServers": {
"mcp-for-page-builders": {
"command": "/path/to/mcp-for-page-builders",
"env": { "WP_TLS_INSECURE": "1" }
}
}
}
Environment Variables
Creating an Application Password
# Via WP-CLI
wp user application-password create admin "mcp-for-page-builders" --porcelain
Or: WordPress Admin → Users → Profile → Application Passwords → Add New.
Tool Reference
Page Management
Post Management
Element Operations
Global Design Tokens
Elementor Settings & Kit
Cache
Cache is cleared automatically after every write operation.
File I/O
Visual Tools
Requires Chrome/Chromium installed. All visual tools support pre_js for page interaction before capture and return inline images visible to the AI.
Example (ui_quality_audit):
{
"name": "ui_quality_audit",
"arguments": {
"url": "https://staging.example.com",
"reference_url": "https://production.example.com",
"run_pagespeed": true,
"pagespeed_strategy": "mobile"
}
}
pre_js — Page Interaction Before Capture
All visual tools accept pre_js (JavaScript to execute after page load) and wait_ms (delay after execution). Use this to click menus, dismiss cookie banners, or expand sections before capture.
{
"name": "visual_compare",
"arguments": {
"url_a": "https://production.com",
"url_b": "https://dev.ddev.site",
"pre_js_a": "document.querySelector('a.burger-menu')?.click()",
"pre_js_b": "document.querySelector('a.burger-menu')?.click()",
"wait_ms": 1500
}
}
If pre_js executes but the page state doesn't change, a warning is included in the result.
Widget Schema & Validation
CSS Mapping
Templates
WordPress Options
Live Editor
Widget Scaffolding
Environment & Setup
Multi-Site Management
Utilities
Local Environment Detection
The ensure_site tool auto-detects local development environments from URLs:
CDP tools automatically check reachability before navigation. If a local URL is unreachable, the error suggests calling ensure_site first.
MCP Bridge Plugin
Some tools require a small companion WordPress plugin: MCP Bridge for Page Builders (mcp-bridge-for-page-builders on wordpress.org).
The plugin exposes additional REST endpoints that WordPress's built-in API doesn't provide:
mcp-for-page-builders/v1/status— health check and version probe used byinstall_bridgemcp-for-page-builders/v1/option— read/write arbitrary WordPress options (used byget_wp_option,set_wp_option, and as a fallback deployment channel for mu-plugin snippets)
Without the bridge, get_wp_option and set_wp_option fall back to the standard wp/v2/settings endpoint, which only exposes a small allowlisted subset of options. The bridge removes that restriction, giving the MCP server full access to any option — including Elementor's internal configuration, Theme Builder conditions, and third-party plugin settings.
The install_bridge tool handles installation automatically using a five-step fallback chain:
- Check if the bridge is already active (no-op if so)
- Auto-install and activate from wordpress.org via the plugins REST API
- Activate if already uploaded but inactive
- Bootstrap via Code Snippets — installs the
code-snippetsplugin, creates a snippet that writes the bridge plugin file, activates the bridge, then removes Code Snippets entirely (no passwords or cookies needed) - Return the PHP snippet for manual installation
The bridge plugin is intentionally minimal — it adds no admin UI, no settings page, and no frontend output. Its sole purpose is to extend the REST API surface available to this MCP server.
Development
Running Tests
# Full cycle: spins up Docker WordPress, runs unit + integration tests, tears down
./tests/run.sh
# Unit tests only (no Docker needed)
./tests/run.sh --unit
# Keep environment running after tests
./tests/run.sh --keep
# Re-run tests against existing environment
./tests/run.sh --retest
Project Structure
src/
├── main.rs — stdio loop, config, tool dispatch (graceful startup)
├── mcp.rs — JSON-RPC 2.0 protocol + stdio transport
├── wp.rs — WordPress HTTP client (reqwest + Basic Auth + unconfigured mode)
├── cdp.rs — Chrome DevTools Protocol (crash recovery, pre_js, local URL check)
├── elementor/ — Element types, tree operations, service layer
└── tools/
├── mod.rs — Tool trait + registry (75 tools)
├── page/ — Page CRUD
├── post/ — Post CRUD
├── element/ — Element operations
├── global/ — Global colors/typography
├── settings/ — Kit schema, experiments
├── visual/ — Screenshots, comparison, diff, match_styles
├── schema/ — Widget schemas, validation
├── template/ — Theme Builder templates
├── file_io/ — Download, upload, backup
├── option/ — WordPress options
├── bridge/ — Bridge plugin + widget scaffolding
├── css_map.rs — CSS-to-Elementor mapping
├── inspect.rs — DOM inspection
├── clone.rs — DOM-to-Elementor cloning
├── editor.rs — Live Elementor editor control
├── ensure_site.rs — Local environment detection + boot
├── setup_wizard.rs — Interactive WP connection setup
├── seed.rs — Demo content generation
├── auth.rs — Browser authentication
└── cache.rs — CSS cache clearing
License
Licensed under the Business Source License 1.1.
- Free to use, modify, and distribute for any purpose including production
- Cannot be sold or rebranded as a separate commercial product without a license
- Change Date: 2030-03-26 — converts to Apache 2.0