For Page Builders
MCP server for WordPress page builders β currently Elementor, with plans to support any page builder with automatic detection
Ask AI about For Page Builders
Powered by Claude Β· Grounded in docs
I know everything about For Page Builders. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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 Β· 74 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
| Variable | Required | Description |
|---|---|---|
WP_URL | β | WordPress site URL (optional β CDP tools work without it) |
WP_APP_USER | β | WordPress username (defaults to admin) |
WP_APP_PASSWORD | β | Application Password (from Users β Profile β Application Passwords) |
WP_TLS_INSECURE | β | Set to any value to accept self-signed certs (DDEV, local dev) |
CHROME_PATH | β | Override Chrome binary path for visual tools |
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
| Tool | Description |
|---|---|
create_page | Create a new page with Elementor data |
get_page | Get page by ID including _elementor_data |
update_page | Update title, status, and/or Elementor data |
delete_page | Delete a page (optional force bypass trash) |
get_page_by_slug | Look up page ID from URL slug |
list_pages | List pages with IDs, titles, slugs, status |
Post Management
| Tool | Description |
|---|---|
create_post | Create a new post |
get_post | Get post by ID |
list_posts | List posts |
update_post | Update a post |
delete_post | Delete a post |
Element Operations
| Tool | Description |
|---|---|
get_element_tree | Flattened view of page structure with paths and IDs |
get_element | Get a single element by ID |
add_element | Insert widget/container at specific position |
update_element | Merge settings into an element (partial update) |
remove_element | Delete element by ID |
move_element | Move element to different parent/position |
duplicate_element | Clone element with new IDs, inserted after original |
find_elements | Search by widget type and/or setting key/value |
Global Design Tokens
| Tool | Description |
|---|---|
get_global_colors | Get all global colors |
set_global_color | Create or update a global color |
delete_global_color | Delete a global color |
get_global_typography | Get all global typography presets |
set_global_typography | Create or update a typography preset |
delete_global_typography | Delete a typography preset |
Elementor Settings & Kit
| Tool | Description |
|---|---|
get_kit_schema | All available kit settings with types and defaults |
get_kit_defaults | Default settings applied to each widget type |
get_experiments | All feature flags and their current state |
set_experiment | Enable/disable an experiment (feature flag) |
Cache
| Tool | Description |
|---|---|
clear_cache | Clear Elementor CSS cache and regenerate styles |
Cache is cleared automatically after every write operation.
File I/O
| Tool | Description |
|---|---|
download_page | Save _elementor_data to a local JSON file |
upload_page | Update page from a local JSON file |
backup_page | Snapshot current state to timestamped file |
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.
| Tool | Description |
|---|---|
screenshot | Full-page screenshot of any URL β returns inline image |
screenshot_page | Screenshot a WordPress page by ID β returns inline image |
visual_compare | Side-by-side stitched comparison of two URLs β returns combined image |
visual_diff | Element-by-element structured comparison with match score β auto-discovers selectors |
extract_styles | Extract computed CSS from a live page element |
inspect_page | Inspect DOM element β bounding box, computed styles, children tree |
clone_element | Clone live DOM element as Elementor JSON |
match_styles | One-shot visual parity: extract CSS β convert to Elementor β apply to element |
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
| Tool | Description |
|---|---|
list_widgets | List all widgets with bundled schemas |
get_widget_schema | Full schema for a widget type β valid settings, aliases |
validate_element | Validate element JSON with "did you mean?" suggestions |
CSS Mapping
| Tool | Description |
|---|---|
css_to_elementor | Convert CSS properties to Elementor widget settings JSON |
Templates
| Tool | Description |
|---|---|
create_template | Create template with auto-activated Theme Builder conditions |
update_template | Update template data, title, or conditions |
get_template | Get template by ID |
list_templates | List all templates |
delete_template | Delete a template |
WordPress Options
| Tool | Description |
|---|---|
get_wp_option | Read any WordPress option |
set_wp_option | Write any WordPress option |
Live Editor
| Tool | Description |
|---|---|
elementor_editor | Control Elementor editor via CDP β open, select widget, set setting, save |
Widget Scaffolding
| Tool | Description |
|---|---|
install_bridge | Install the MCP Bridge companion plugin |
create_widget | Scaffold and deploy custom Elementor widget PHP class |
Environment & Setup
| Tool | Description |
|---|---|
ensure_site | Check URL reachability, auto-detect and boot DDEV/Lando environments |
setup_wizard | Interactive WordPress connection setup with options and instructions |
Multi-Site Management
| Tool | Description |
|---|---|
authenticate | Browser-based WordPress authentication β no credentials in config |
connect_site | Add a site connection (credentials stored internally) |
switch_site | Switch active site without restart (hot-reload) |
list_sites | List all stored site connections |
disconnect_site | Remove a stored site connection |
Utilities
| Tool | Description |
|---|---|
seed_content | Create demo pages with various layouts and widgets |
get_session_state | Recover context after crash β shows active site, pending ops |
Local Environment Detection
The ensure_site tool auto-detects local development environments from URLs:
| Pattern | Environment | Action |
|---|---|---|
*.ddev.site | DDEV | Check ddev list, start if stopped, verify HTTP |
*.lndo.site | Lando | Check lando list, report status |
localhost:*, 127.0.0.1:* | Local | HTTP reachability check |
| Everything else | Remote | HTTP reachability check |
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 (74 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
