Elementor MCP

一个用于处理基于 Elementor 构建的 WordPress 网站的 MCP 服务器——读取页面结构、编辑小部件、管理全局设计令牌，并且不会破坏任何东西。

Elementor 将整个页面布局以 JSON blob 的形式存储在受保护的 postmeta 键（_elementor_data）中。WordPress REST API 无法读取或写入它，这正是为什么通用的 WordPress MCP 服务器可以列出你的页面，却无法改动页面上的内容。本项目填补了这一空白。

你能获得什么

• 50 个工具，涵盖页面结构、元素编辑、小部件模式、全局设计、模板、历史和全站搜索。

• 实时小部件模式。 控件定义从目标站点自身的 Elementor 注册表中读取，因此你获得的模式描述的正是该站点实际安装的小部件——核心版、Pro 版以及任何第三方扩展包——而不是一份会过时的硬编码列表。

• 安全的并发写入。 每次写入都携带读取页面时的内容哈希；如果页面在底层发生了变化，写入将被拒绝。不会有静默覆盖。

• 撤销。 每次写入都会先对布局进行快照。elementor_restore_snapshot 可回滚最后一次更改。

• 原子化批量操作。 多步骤重构要么作为一个整体操作应用，要么完全不应用——页面绝不会处于编辑到一半的状态。

• 多站点。 一个服务器可以面向多个 WordPress 安装，每个安装都可以按名称寻址，并且每个都可以独立地标记为只读。

Related MCP server: elementor-mcp-agent

架构

两个部分，因为单独任何一个都无法工作：

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

plugin/elementor-mcp-bridge/ —— 一个 WordPress 插件，暴露了 elementor-mcp/v1 REST 命名空间。它通过 Elementor 自己的 Document::save() 读取和写入 Elementor 文档（这是编辑器使用的同一条路径，因此数据清理、修订和 CSS 重新生成都能正确进行），并内省实时小部件注册表以获取模式。

src/ —— MCP 服务器。它在自己的进程中持有元素树，并在那里完成结构性工作，因此一个 400 KB 的页面也能被编辑，而该 JSON 永远不会进入模型的上下文。

这种拆分是有意为之。元素树的操作逻辑放在 TypeScript 中，并针对 59 个用例进行了单元测试；PHP 端保持精简，并委托给 Elementor。

安装

1. 桥接插件

构建一个可安装的 zip 包，并通过 wp-admin 中的 插件 → 安装插件 → 上传插件 上传：

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

如果有任何文件未通过 php -l 检查，脚本会拒绝构建，因此损坏的插件无法被打包。

或者直接安装：

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

需要 WordPress 5.9+、PHP 7.4+ 以及 Elementor 3.x 或 4.x。

确认它已生效：

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

在 Windows 上，curl 是 Invoke-WebRequest 的别名，不接受 -u。请改用内置的诊断脚本，它会依次检查可达性、REST API、插件激活和凭据，因此失败时会告诉你具体是哪一项出了问题：

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

或者使用 curl.exe 强制使用真正的 curl，而不是别名。

2. 应用程序密码

在 wp-admin 中转到 用户 → 个人资料 → 应用程序密码，添加一个名为 elementor-mcp 的密码，并复制生成的值。这不是该账户的登录密码；它可以被独立撤销。

桥接插件在每个路由上都检查真实的 WordPress 权限，因此代理只能执行该用户手动能够执行的操作。请为它提供一个满足你用途的最小角色账户——Editor（编辑）通常就足够，只有当你需要更改站点级设计设置时才需要 Administrator（管理员）。

3. 服务器

npm install
npm run build

配置

单站点：

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

多站点——将 ELEMENTOR_MCP_SITES 设置为一个 JSON 数组：

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

连接客户端

Claude Code:

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

或者直接编辑 MCP 客户端配置：

{
  "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"
      }
    }
  }
}

如何用好它

工具描述会引导你这样做，但简而言之：

1. 每个站点调用一次 elementor_site_status —— 获取版本、小部件数量以及已认证用户可执行的操作。

2. 使用 elementor_get_outline 获取元素 ID。除非你真的需要每一项设置，否则不要使用 elementor_get_page_tree；大纲的体积只有其一小部分。

3. 在设置不熟悉的小部件设置之前，先使用 elementor_get_widget_schema。控件名称无法凭空猜出，错误的键会静默保存且没有可见效果——这是 Elementor 自动化出错最常见的原因。

4. 任何多步骤操作都使用 elementor_batch_edit。

5. 使用 elementor_render_page 确认结果。

响应式设置使用 _tablet 和 _mobile 后缀（padding、padding_tablet、padding_mobile）；模式会标记哪些控件是响应式的，并明确列出确切的键名。

安全模型

要允许永久删除和已提交的全站替换，请在 wp-config.php 中添加：

define( 'EMCP_ALLOW_DESTRUCTIVE', true );

工具

完整参考见 docs/TOOLS.md。按领域划分：

• 站点 — elementor_list_sites、elementor_site_status、 elementor_native_mcp_call

• 页面 — 列表、获取、大纲、创建、复制、删除、渲染、更新元数据、完整树

• 元素 — 获取、查找、添加小部件、添加容器、更新、移动、复制、删除、重新排序、包裹、批量编辑、替换树

• 小部件 — 列表、模式、元素类型、动态标签

• 设计 — 全局设置、设置全局颜色、更新全局设置、自定义 CSS、全局类、刷新 CSS

• 模板 — 列表、获取、保存、应用、导出、导入

• 历史 — 快照（列表/创建/恢复）、修订（列表/恢复）

• 内容 — 搜索、查找并替换、小部件使用情况、媒体列表、图片上传

Elementor 自带的 MCP 模块

Elementor 4.3 随附了一个内置的 MCP 模块，由 WordPress Abilities API 控制启用，专注于 v4 的原子特性——全局类、变量、组件、组合。只要该模块存在，elementor_native_mcp_call 就会直接代理到它，因此除了本服务器的全部功能之外，你还能获得这些能力。

它并不能替代本服务器：它要求安装 Elementor 4.3+ 及可选依赖，而且它不覆盖经典的 section/column/widget 模型——绝大多数实际运行的 Elementor 站点都基于这一模型构建。elementor_site_status 会报告它是否可用。

开发

npm run build            # compile
npm test                 # 59 unit tests
npm run typecheck        # source and tests
npm run smoke            # boot the server and exercise the MCP handshake
npm run docs             # regenerate docs/TOOLS.md from the running server
php tests/plugin-load.php   # load the plugin and register all 32 routes
./scripts/package-plugin.sh # build the installable zip

tests/plugin-load.php 会使用桩（stub）化的 WordPress 函数加载桥接插件，并断言每个路由都有可调用的处理程序和权限回调。它不能替代真实站点，但它能捕获那些否则会被 zip 包隐藏、直到上传时才会暴露的激活致命错误。

许可证

MIT。参见 LICENSE。