elementor-mcp-agent

Agency-grade MCP server for WordPress Elementor — multi-site fleet management, safe page/widget-level editing, template export/import, version tracking with snapshot/rollback.

Agency-grade MCP server for WordPress Elementor.Multi-site management, safe Elementor edits with backup + auto-rollback + CSS flush, template export/import, global widget detection, screenshots, WP-CLI escape hatch.

Built for agencies running many client sites on Elementor / Elementor Pro who want Claude (or any MCP client) to drive the toil —without breaking pages.

elementor-mcp-agent was built end-to-end with Claude Code over ~48 hours. The process is intentionally open:

- Architecture, code, tests, docs — all generated through Claude Code pair-programming sessions
- The 7 bugs documented inthis post-mortemwere caught in real E2E testing against a live WordPress + Elementor install, not after the fact
- v1.2's post-write verification pattern was shipped 2 hours after a reader's comment (Mads Hansen on Dev.to) — the changelog credits the source

export ELEMENTOR_MCP_SITES='[{ "id": "client-acme", "url": "https://acme.example.com", "username": "admin", "application_password": "xxxx xxxx xxxx xxxx xxxx xxxx", "ssh": { "host": "host.example.com", "user": "username", "port": 22, "path": "/path/to/wordpress", "wp_cli_path": "wp" } }]'

Generate theWordPress Application Passwordathttps://{your-site}/wp-admin/profile.php#application-passwords-section.

Thesshblock isoptionalbut unlocks8 additional tools(WP-CLI escape hatch + reliable custom-postmeta backups). The MCP works without SSH — backups go to local JSON files instead.

wp_cli_pathauto-detects if omitted (trieswp, then~/bin/wp.phar, then~/wp-cli.phar).

{ "mcpServers": { "elementor": { "command": "npx", "args": ["-y", "elementor-mcp-agent"], "env": { "ELEMENTOR_MCP_SITES": "[{\"id\":\"acme\",\"url\":\"https://acme.com\",\"username\":\"admin\",\"application_password\":\"...\"}]" } } } }

- list_sites— enumerate the pool
- ping_site— auth + version probe
- site_health— multi-call health snapshot

- list_elementor_pages— pages in builder mode
- read_page_elementor— parsed summary + optional full tree
- list_widgets_in_page— flat widget inventory with excerpts
- list_global_widgets— shared widgets (edit one → affects every page using it)
- preflight_check— validate a page is safe to edit
- elementor_find_replace— text replace withdry-run → token → apply → backup → validate → rollback if invalid
- list_elementor_backups/restore_elementor_backup— full restore chain with pre-restore safety backup
- duplicate_elementor_page— clone within a site (data + page_settings + edit_mode)

- list_elementor_templates— Theme Builder distinguished from regular library
- export_elementor_template— portable JSON
- import_elementor_template— drop into target site
- apply_template_to_page— push template data onto an existing page

- wp_cli_run— arbitrary wp-cli command with destructive-pattern detection + confirmation
- wp_search_replace—wp search-replacewith mandatory dry-run
- wp_elementor_flush_css— 3-level fallback
- wp_plugin_list/wp_plugin_update(with confirmation)

- screenshot_page— headless Chrome PNG of any URL
- compare_screenshots— SHA-256 + byte-delta

- read_widget— fetch one widget by id (read-only)
- update_widget_settings— shallow-merge settings, with backup + validate + flush
- delete_widget— remove a widget from its parent container
- duplicate_widget— clone as sibling with fresh id
- swap_widget_type— replace widgetType + settings, preserve id + position
- add_widget— append a widget into a parent container
- move_widget— move a widget between containers (with position)

- bulk_find_replace_site— find/replace across every Elementor page of one site, per-page backup + validate + flush
- fleet_find_replace— same acrossevery site in the pool(sequential, dry-run mandatory)
- restore_from_file— restore_elementor_datafrom a JSON file backup, with pre-restore safety backup

- check_elementor_versions— flag outdated installs against wordpress.org latest

Every mutating widget tool re-reads the page from canonical WPafter the writeand surfaces persisted state to the model. The HTTP write API can lie — return 200 OK while plugin filters or REST quirks silently drop the payload. This contract makes that observable.

{ "mutated": true, // false = no-op OR silent drop "warnings": [], // non-fatal issues "verification": { "method": "Re-read /wp/v2/pages/42 and check widget abc settings…", "reread_ok": true, "matches_requested": true, // false = write API lied "persisted": { / canonical state / }, "notes": "…explanation when something diverged" } }

Ifverification.matches_requested === false, treat as a failure even if the HTTP layer said OK. The original payload survives inbackup_meta_key— restore viarestore_elementor_backup.

Hardcoded insrc/elementor/policies.ts:

BACKUP_BEFORE_WRITE = true BACKUP_PAGE_SETTINGS = true VALIDATE_JSON_AFTER_EDIT = true BLOCK_GLOBAL_WIDGET_WRITES_BY_DEFAULT = true CONFIRMATION_TTL_SECONDS = 60 GLOBAL_WIDGET_CONFIRMATION_TTL_SECONDS = 30 FLUSH_CSS_AFTER_WRITE = true MAX_ELEMENTOR_DATA_BYTES = 5_000_000

And these wp-cli patterns arehard-blockedregardless of confirmation:

- rm -rf
- sudo *
- db reset --yes/db drop --yes

v1.0.0 was tested in real conditions against a live WordPress install with Elementor 4.0.9:

- ✅ 21/24 tools validated end-to-end at the v1.0.0 baseline (the suite now exposes34— seeTools)
- ✅ find_replace → backup → restore round-trip preserves data
- ✅ duplicate_page copies data + page_settings + edit_mode
- ✅ apply_template_to_page with auto-backup
- ✅ wp_cli_run destructive flow (post delete) requires confirmation
- ✅ screenshots identical detection via SHA-256
- ✅ CSS flush useswp elementor flush-csswhen SSH available, falls back to option-delete otherwise

The fastest way to support the project is a⭐ star on GitHub— it helps other agencies running Elementor sites find this and tells me what to keep building.

- Open anissuefor bugs, edge cases, or missing tools
- Start adiscussionfor design or workflow questions
- Share what you built with it — I'd love to hear

A TypeScript-based MCP server that acts as a companion to the Drupal MCP module, communicating via STDIO.