Elementor MCP

An MCP server for working on Elementor-built WordPress sites — reading page structure, editing widgets, managing global design tokens, and doing it without breaking anything.

Elementor keeps its entire page layout as a JSON blob in a protected postmeta key (_elementor_data). The WordPress REST API will not read or write it, which is why generic WordPress MCP servers can list your pages but cannot touch what is on them. This project closes that gap.

What you get

• 50 tools covering page structure, element surgery, widget schemas, global design, templates, history and site-wide search.

• Live widget schemas. Control definitions are read from the target site's own Elementor registry, so the schema you get describes exactly the widgets that site has installed — core, Pro, and any third-party addon pack — instead of a hard-coded list that goes stale.

• Safe concurrent writes. Every write carries the content hash the page was read at and is rejected if the page changed underneath. No silent overwrites.

• Undo. Every write snapshots the layout first. elementor_restore_snapshot rolls back the last change.

• Atomic batches. Multi-step restructuring applies as one operation, or not at all — a page is never left half-edited.

• Multi-site. One server can front many WordPress installs, each addressable by name, each independently markable read-only.

Related MCP server: elementor-mcp-agent

Two ways to connect

The bridge plugin can be used two ways, and they are independent — pick whichever fits how you work:

1. WordPress serves MCP directly (recommended). The plugin exposes a JSON-RPC 2.0 endpoint at /wp-json/elementor-mcp/v1/mcp — the same "Streamable HTTP" transport most remote MCP servers use, running statelessly (no session, no persistent connection, which is exactly how a PHP request already works). Point an MCP client — including a claude.ai custom connector — at that URL and authenticate with a WordPress application password. Nothing to install beyond the plugin itself, and it works from claude.ai on the web, desktop or mobile.

MCP client  ──HTTPS──▶  WordPress
                         └── Elementor MCP Bridge (this repo)
                              ├── /mcp        (JSON-RPC 2.0, 49 tools)
                              ├── /documents   ┐
                              ├── /kit         │ plain REST, same logic
                              ├── /templates   │ the MCP endpoint calls
                              └── ...          ┘

2. A local Node server (src/), talking to the bridge's REST API. Useful for development, for MCP clients that only support local stdio servers, or when you would rather the element-tree logic run outside the PHP process.

MCP client  ──stdio──▶  elementor-mcp (Node)  ──REST──▶  WordPress
                                                          └── Elementor MCP Bridge

Both paths end up calling the same Elementor APIs — Document::save() (the same path the editor itself uses, so sanitisation, revisions and CSS regeneration all happen correctly) and the live widget registry for schemas. The element-tree mutation logic (insert, move, duplicate, reorder, wrap, batch) is implemented twice, once in each language, and kept in parity deliberately: 236 PHP assertions and 41 TypeScript ones exercise the same cases side by side, so a change to one is expected to show up as a matching change in the other's test file.

Install

1. The bridge plugin

Build an installable zip and upload it through Plugins → Add New → Upload Plugin in wp-admin:

./scripts/package-plugin.sh
# build/elementor-mcp-bridge-1.2.0.zip

The script refuses to build if any file fails php -l, so a broken plugin cannot be packaged.

Or install it directly:

rsync -a plugin/elementor-mcp-bridge/ user@host:/var/www/site/wp-content/plugins/elementor-mcp-bridge/
wp plugin activate elementor-mcp-bridge     # or activate in wp-admin

Requires WordPress 5.9+, PHP 7.4+ and Elementor 3.x or 4.x.

Confirm it is live:

curl -u 'user:app password' https://example.com/wp-json/elementor-mcp/v1/status

On Windows, curl is an alias for Invoke-WebRequest and does not accept -u. Use the bundled diagnostic instead, which checks reachability, the REST API, plugin activation and credentials in order so a failure tells you which one broke:

.\scripts\Test-Bridge.ps1 -SiteUrl https://example.com -Username admin -AppPassword 'abcd efgh ijkl mnop'

Or force real curl with curl.exe rather than the alias.

2. An application password

In wp-admin go to Users → Profile → Application Passwords, add one named elementor-mcp, and copy the generated value. This is not the account's login password; it can be revoked independently.

The bridge checks a real WordPress capability on every route, so the agent can only do what that user could do by hand. Give it an account with the least role that covers your use — Editor is usually enough, Administrator only if you need to change site-wide design settings.

3. The server

npm install
npm run build

Configure

Single site:

WORDPRESS_URL=https://example.com
WORDPRESS_USERNAME=your-user
WORDPRESS_APP_PASSWORD="abcd efgh ijkl mnop qrst uvwx"

Several sites — set ELEMENTOR_MCP_SITES to a JSON array:

[
  { "name": "live",    "url": "https://example.com",         "username": "u", "appPassword": "..." },
  { "name": "staging", "url": "https://staging.example.com", "username": "u", "appPassword": "...", "readOnly": true }
]

Connecting a client to the WordPress MCP endpoint (recommended)

The endpoint is https://example.com/wp-json/elementor-mcp/v1/mcp.

claude.ai (web or desktop): Settings → Connectors → Add custom connector, paste the URL, and continue — no token to generate or paste anywhere. It runs an OAuth flow on its own: you're sent to your site to log in (if needed) and approve the connection, then straight back to claude.ai, connected. See Authentication for what that mints behind the scenes.

Any other MCP client: if it accepts a static token instead, use base64(username:app_password) as either HTTP Basic or a bearer token:

echo -n 'your-user:abcd efgh ijkl mnop qrst uvwx' | base64

To check the endpoint directly, either way works for a plain curl test:

curl -u 'your-user:abcd efgh ijkl mnop qrst uvwx' \
  -X POST https://example.com/wp-json/elementor-mcp/v1/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Connecting a client to the local Node server

Claude Code:

claude mcp add elementor -- node /path/to/elementor-mcp/dist/index.js

Or by editing an MCP client config directly:

{
  "mcpServers": {
    "elementor": {
      "command": "node",
      "args": ["/path/to/elementor-mcp/dist/index.js"],
      "env": {
        "WORDPRESS_URL": "https://example.com",
        "WORDPRESS_USERNAME": "your-user",
        "WORDPRESS_APP_PASSWORD": "abcd efgh ijkl mnop qrst uvwx"
      }
    }
  }
}

Authentication

Two ways in, and which one applies depends on the client, not on you:

Direct — HTTP Basic or bearer, with an application password. Every route — REST and MCP alike — accepts a WordPress application password (Users → Profile → Application Passwords) sent as HTTP Basic:

Authorization: Basic base64(username:app_password)

That is native to WordPress; no code in this plugin handles it. The MCP endpoint additionally accepts the same value as a bearer token —

Authorization: Bearer base64(username:app_password)

— for MCP clients whose connector UI only exposes a single "token" field. Same credential, two header shapes; there is no separate "MCP token" to generate. This is what the curl examples in this README use, and it is enough for the local Node server, direct REST calls, and any MCP client that accepts a static token.

OAuth — for clients that require it. claude.ai's custom connector, on both web and desktop, does not accept a static token: it runs a full authorization-code flow with PKCE (RFC 6749 + RFC 7636) against the connector's own origin, the same as any other OAuth-only remote MCP server. The plugin implements that flow — GET/POST /authorize, POST /token, plus the RFC 8414 and RFC 9728 discovery documents — entirely to satisfy this requirement; it does not add any capability beyond what the direct route already offers, and the local Node server never needs it.

You do not generate anything for this path yourself. Add the custom connector in claude.ai with the URL https://example.com/wp-json/elementor-mcp/v1/mcp and it drives the flow on its own: a redirect to your site to log in (if not already) and approve access, then straight back to claude.ai, connected. What gets minted behind the scenes is, again, an ordinary application password — named Claude MCP (OAuth, <timestamp>) — so it shows up individually in Users → Profile → Application Passwords and can be revoked from there like any other, with nothing extra to track.

The redirect target is checked against an allow-list (emcp_oauth_allowed_redirect_uris, defaulting to claude.ai's confirmed callback) before any code is issued, so this cannot be turned into an open redirect by a crafted link.

CGI/FastCGI

If direct authentication fails with a 401 and the credentials are correct, the server is likely running under CGI/FastCGI, which strips the Authorization header before PHP sees it. Add this to .htaccess above the WordPress block:

RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule .* - [e=HTTP_AUTHORIZATION:%1]

One site, or many

The WordPress-hosted MCP endpoint has exactly one site: the one it runs on. Its 49 tools take no site argument — there is nothing to disambiguate.

The local Node server can front several WordPress installs from one process (see Configure above), which is why its tools all accept an optional site argument. If you only ever work on one site, this distinction will not come up; it matters once you are managing more than one install from a single MCP client.

How to use it well

The tool descriptions steer toward this, but the short version:

1. elementor_site_status once per site — versions, widget count, what the authenticated user may do.

2. elementor_get_outline to get element ids. Do not reach for elementor_get_page_tree unless you genuinely need every setting; outlines are a fraction of the size.

3. elementor_get_widget_schema before setting unfamiliar widget settings. Control names are not guessable, and a wrong key saves silently with no visible effect — this is the single most common way Elementor automation goes wrong.

4. elementor_batch_edit for anything multi-step.

5. elementor_render_page to confirm the result.

Responsive settings use _tablet and _mobile suffixes (padding, padding_tablet, padding_mobile); the schema marks which controls are responsive and spells out the exact keys.

Safety model

To allow permanent deletes and committed site-wide replaces, add to wp-config.php:

define( 'EMCP_ALLOW_DESTRUCTIVE', true );

Tools

Full reference in docs/TOOLS.md. By area:

• Sites — elementor_list_sites, elementor_site_status, elementor_native_mcp_call

• Pages — list, get, outline, create, duplicate, delete, render, update metadata, full tree

• Elements — get, find, add widget, add container, update, move, duplicate, delete, reorder, wrap, batch edit, replace tree

• Widgets — list, schema, element types, dynamic tags

• Design — globals, set global colour, update globals, custom CSS, global classes, flush CSS

• Templates — list, get, save, apply, export, import

• History — snapshots (list/create/restore), revisions (list/restore)

• Content — search, find and replace, widget usage, media list, image upload

Elementor's own MCP module

Elementor 4.3 ships a built-in MCP module, gated behind the WordPress Abilities API and focused on v4 atomic features — global classes, variables, components, compositions. Where it is present, elementor_native_mcp_call proxies straight through to it, so you get those abilities alongside everything here.

It is not a replacement for this server: it requires Elementor 4.3+ with optional dependencies installed, and it does not cover the classic section/column/widget model that the overwhelming majority of live Elementor sites are built on. elementor_site_status reports whether it is available.

Development

npm run verify               # every check below, except docs and packaging
npm run build                # compile the Node server
npm test                     # 60 TypeScript unit tests
npm run typecheck            # source and tests
npm run smoke                # boot the Node server and exercise the MCP handshake
npm run test:guard           # drive the Node server against a mock bridge
npm run docs                 # regenerate docs/TOOLS.md from the running Node server
php tests/plugin-load.php    # load the plugin, register all 33 REST routes
php tests/tree-mutators.php  # 236 assertions: PHP tree mutators against the same
                              # cases as tests/tree.test.ts
php tests/mcp-endpoint.php   # 51 assertions: full JSON-RPC round trips against an
                              # in-memory WordPress — initialize, tools/list, and
                              # real element edits through the hash-guarded write path
php tests/oauth-flow.php     # 46 assertions: the full authorization-code + PKCE
                              # round trip, driven directly against EMCP_OAuth
./scripts/package-plugin.sh  # build the installable zip

Four PHP harnesses, in order of what they prove:

• tests/plugin-load.php — the plugin loads and every route resolves to a callable handler and permission callback. Catches activation fatals before they reach a zip upload.

• tests/tree-mutators.php — the PHP element-tree mutators (insert, move, duplicate, reorder, wrap, batch) behave identically to the TypeScript ones, case for case.

• tests/mcp-endpoint.php — the JSON-RPC layer itself: protocol negotiation, tool discovery, and real tool calls against an in-memory post store, including permission denial, the destructive-operation confirm gate, and the snapshot-then-restore undo path. It stubs WordPress rather than Elementor, so it exercises the bridge's own fallback write path, not Document::save() — that half still needs a real site.

• tests/oauth-flow.php — discovery metadata; the not-logged-in-redirects- to-login case; consent approve and deny; PKCE accepted with the correct verifier and rejected with the wrong one; a used code rejected on replay; a mismatched redirect_uri rejected; an untrusted redirect_uri refused as a page rather than ever becoming a redirect; and the token this endpoint issues successfully authenticating through the existing bearer-token shim with no changes needed there. It calls EMCP_OAuth's private handlers directly via reflection, since the real request router ends in exit.

tests/capability-guard.mjs runs the built server over stdio against tests/mock-bridge.mjs, a stand-in bridge whose element registry, widget registry and stored documents a test dictates. That reaches the behaviour that depends on the site rather than on our code: refusing an element type the site cannot render, surfacing a save warning, standing down when a site reports no registry at all, and re-applying a write that raced another editor. It asserts against the mock's write log rather than the wording, so a regression that keeps the message and loses the guard still fails.

Licence

MIT. See LICENSE.