Elementor Pro Tools
Complete reference for the 10 Elementor Pro tools in Royal MCP Pro. Widget CRUD by element ID, template clone-and-retarget, theme builder ops with display conditions, and bulk setting replacement across widget instances. Every destructive operation returns a 72-hour undo token.
Most tools work with the free Elementor plugin. Two tools — elementor_apply_theme_builder_conditions and elementor_save_template_with_conditions when using conditions — require the paid Elementor Pro plugin for conditions to be enforced at render time. Without Elementor Pro they still store the condition strings as meta (they just won't fire on the front end). Not to be confused with Royal MCP Pro, which is what gates these tools in the first place.
Prerequisites
- Elementor active (free or Pro; some tools have specific Elementor Pro-plugin requirements — noted per tool)
- Royal MCP Pro installed and licensed (see Getting Started)
- MCP client connected to your site
Tools that touch content refuse when the target post has no _elementor_data (i.e. was never edited with Elementor). Return code: source_has_no_elementor_data.
Shared safety layer
Every Elementor Pro write tool runs through the same safety layer used by the Divi Pro tools:
- Cap checks. Every tool requires
edit_postsat minimum, plus per-objectedit_post/read_postwhere applicable. - Fresh element IDs on clone/apply.
elementor_clone_templateandelementor_apply_template_to_pageregenerate every element ID on the copy so the duplicate opens in the Elementor editor without ID collisions. - Builder-session guard. The portfolio-wide
Builder_Safetyhelper checks WordPress core's_edit_lockon the target post before writes. If the Elementor editor is open on the target with a lock set within the last 150 seconds, writes soft-error with abuilder_session_activecode. Passforce: trueto bypass when you know the state. - Undo tokens on every destructive tool. Every write returns a 72-hour undo token. Most Elementor undo handlers restore the full prior
_elementor_data(element-level operations can't undo cleanly without the full-post snapshot; the whole-post restore is deliberate). - Audit Log row on every call. Success, error, and undone states all produce audit rows.
The 10 tools
elementor_clone_template
Duplicate an Elementor page/post/template with fresh element IDs. Optional retarget block applies text + image URL substitutions to the clone in the same call.
Arguments
| Name | Type | Description |
|---|---|---|
source_post_id required | integer | Post/page/template ID to clone from. Must have _elementor_data. |
new_title required | string | Title for the created post. |
new_status | string | One of draft (default) / publish / private / pending. |
retarget | object | Optional bulk substitutions applied before write: text_replacements: [{find, replace, case_insensitive?}], image_replacements: [{old_url, new_url}]. |
Example
Clone Elementor page 42 as "Services V2 Test", swap the text "Original Company Name" to "New Company Name", and swap image https://example.com/old-hero.jpg for https://example.com/new-hero.jpg using elementor_clone_template with retarget.Undo: 72h token — deletes the created post.
elementor_apply_template_to_page
Apply an elementor_library template to a target page. mode=merge appends (position=top|bottom); mode=replace overwrites. Every applied element gets a fresh ID.
Arguments
| Name | Type | Description |
|---|---|---|
target_post_id required | integer | The page/post to apply the template to. |
template_id required | integer | Post ID of an elementor_library entry. |
mode | string | merge (default) or replace. |
position | string | Merge mode only. top or bottom (default). |
Undo: 72h token — restores the prior _elementor_data.
elementor_save_template_with_conditions
Create an elementor_library template and attach Theme Builder display conditions in one call. Conditions use Elementor Pro's Conditions_Manager format (include/general, include/singular/post/12, exclude/...). Elementor Pro required for conditions to be enforced at render; without it, conditions are still stored as meta.
Arguments
| Name | Type | Description |
|---|---|---|
title required | string | Template display title. |
template_json required | string | JSON-encoded array of Elementor elements. |
template_type | string | One of page (default) / section / header / footer / single / archive / popup. |
conditions | array<string> | Optional. Condition strings applied to the template. |
Undo: 72h token — deletes the created template.
elementor_update_widget
Update settings on any widget / container / section / column by element ID. settings is shallow-merged into the existing settings object (nested objects are replaced wholesale, not deep-merged).
Arguments
| Name | Type | Description |
|---|---|---|
post_id required | integer | Post the element lives on. |
element_id required | string | Elementor element ID (8-char hex). |
settings required | object | Partial settings object to merge onto the target element. |
Undo: 72h token — restores the full prior _elementor_data.
elementor_delete_widget
Delete a widget/container/section/column by ID.
Arguments
| Name | Type | Description |
|---|---|---|
post_id required | integer | Post the element lives on. |
element_id required | string | Element ID to delete. |
Undo: 72h token — restores the full prior _elementor_data (deleted element returns to its original position).
elementor_create_widget
Insert a new widget/container into an existing Elementor page. Raw-settings path — caller supplies the full settings object. parent_id targets a specific container/column; omit to append at document root.
Arguments
| Name | Type | Description |
|---|---|---|
post_id required | integer | Target post. |
widget_type required | string | Elementor widget slug (heading, button, image, html, wp-widget-text, etc). |
settings | object | Full Elementor settings object. |
elType | string | One of widget (default) / container / section / column. |
parent_id | string | Optional. Element ID to insert under. Root append if omitted. |
position | integer | Optional. Zero-indexed position within parent. |
Undo: 72h token — removes the created element.
elementor_apply_theme_builder_conditions
Overwrite the Theme Builder display conditions on an existing elementor_library template. Conditions use Conditions_Manager format. Requires Elementor Pro for enforcement (stored either way).
Arguments
| Name | Type | Description |
|---|---|---|
template_id required | integer | Template post ID. |
conditions required | array<string> | Condition strings (e.g. include/general, include/singular/page/42, exclude/archive/product_cat). |
Undo: 72h token — restores prior conditions.
elementor_bulk_replace_widget_setting
Bulk update a specific setting on every widget matching widget_type on a page. Supports dry_run to return the match count without writing.
Arguments
| Name | Type | Description |
|---|---|---|
post_id required | integer | Target post. |
widget_type required | string | Widget slug to match (e.g. button, heading). |
setting_key required | string | Settings key to overwrite on every matching widget. |
new_value required | any | New value. Any JSON-serializable type (string, number, boolean, array, object). |
dry_run | boolean | When true, return match count without writing. |
Undo: 72h token (non-dry-run only) — restores the full prior _elementor_data.
elementor_export_theme_builder_template
Read-only export of a Theme Builder template as a JSON-serializable object suitable for cross-site import. Returns content tree, conditions, template_type, and page_settings.
Arguments
| Name | Type | Description |
|---|---|---|
template_id required | integer | Template post ID to export. |
No undo (read-only).
elementor_update_widget_setting
Fine-grained scoped variant of elementor_update_widget: update or delete ONE setting on a single element by ID. Signature: post_id + element_id + setting (flat key or one-level dot path) + value (any JSON value; pass null to delete). Atomic widgets (widgetType prefixed a- or e-) refused. Guarded by Builder_Safety.
Arguments
| Name | Type | Description |
|---|---|---|
post_id required | integer | Post containing the element. |
element_id required | string | Elementor element ID (8-char hex). |
setting required | string | Flat setting key (e.g. title, text, link.url). Dot-path supported for one level of nesting. |
value | any | New value. Pass null to DELETE the key. |
force | boolean | Bypass Builder_Safety guard. See Builder Session Detected. |
Response
Returns action: "updated" (key existed, value changed) | "created" (key did not exist) | "deleted" (value=null and key existed) | "unchanged" (value already equal — no write, no undo).
Undo restores full prior _elementor_data.
Still Stuck? Two-Step Support Path
If an Elementor Pro tool isn't behaving the way you expected, work through these two steps in order — most tool-level failures resolve at Step 1 because they're actually MCP-connection or host-layer issues, not Elementor-specific.
Step 1: Start with the Royal MCP Troubleshooting Guide
Royal MCP Troubleshooting — Start Here covers MCP-layer issues. If Claude can't reach your site at all, the tool call never fires — that guide is where to start.
For Pro-specific patterns:
- Builder session detected — write tools soft-erroring because the Elementor editor is open on the target post
- Undo token errors — expired, consumed, or handler missing
- Pro tool returned upgrade prompt with valid license
Step 2: Email priority support
If you've worked through Start Here and the relevant Pro-specific doc and the issue still isn't resolved, email priority support from your purchase email address at support@royalplugins.com. Priority email support is included with your license — typical response within 24 hours. Never include your license key in email; we look it up from your purchase address.
- Your hosting provider (SiteGround, Cloudways, Hostinger, Kinsta, WP Engine, Liquid Web, self-hosted VPS, etc.)
- Royal MCP Pro version from WP Admin → Plugins
- Elementor version from WP Admin → Plugins, plus Elementor Pro version if installed
- Active caching plugins (LiteSpeed Cache, WP Rocket, W3 Total Cache, SpeedyCache, Hummingbird, none)
- Active security plugins (Wordfence, Defender Pro, Solid Security, NinjaFirewall, none)
- Cloudflare or CDN in front of the site? If yes, is “Manage AI Bots” or “Bot Fight Mode” on?
- Which MCP client — claude.ai web custom connector, Claude Desktop with
mcp-remote, ChatGPT MCP, Cursor, or another MCP-compatible client - The exact Elementor tool name and args you called (e.g.
elementor_update_widgetwithpost_id: 42, element_id: "abc12345", settings: {...}) - The exact error message returned (from the MCP client's chat surface), plus any
ofid_xxxxxreference code if claude.ai shows one - Screenshot of the most recent
oauth:row in Activity Log AND the most recent Pro tool row in Audit Log with View Details expanded (or confirmation that the logs are empty after a reproduced failure) - The target post's edit URL (WP admin URL for the Elementor editor on that post) so we can visually confirm expected element IDs