elementor-mcp-agent

elementor-mcp-agent

面向代理机构的 WordPress Elementor MCP 服务。 管理多个站点，安全编辑 Elementor（支持备份、自动回滚和 CSS 刷新），导出/导入模板，检测全局小工具、截取屏幕截图，并提供 WP-CLI 应急通道。

专为使用 Elementor / Elementor Pro 管理众多客户网站的代理机构打造，让 Claude（或任何 MCP 客户端）处理繁琐工作，而不会破坏页面。

---

构建方式

elementor-mcp-agent 使用 Claude Code 在约 48 小时内端到端构建完成。整个过程刻意保持公开：

• 架构、代码、测试、文档——全部通过 Claude Code 结对编程会话生成
• 这篇复盘记录的 7 个错误，都是在真实的端到端测试中，对运行中的 WordPress + Elementor 安装进行测试时发现的，而不是事后才发现
• v1.2 的写入后验证模式在读者发表评论后 2 小时内发布（Mads Hansen 在 Dev.to 上的评论）——更新日志注明了来源

这不是那种凭感觉编写后就丢给用户的软件。每个版本发布前都会经过 lint、类型检查、27 项单元测试，以及（v1.0）针对真实 WordPress 安装的完整端到端测试。MCP 本身硬编码了防护措施，可阻止模型执行具有破坏性的 WP-CLI 调用。

我经营着一家小型 WordPress 代理机构，每天都在客户网站上使用这个工具。如果你对将 Agent 代码生成用于生产基础设施持怀疑态度，整个提交历史都已公开——欢迎自行评判。

---

为什么要开发这个项目

如今 GitHub 上有 25 个以上的 WordPress MCP 服务，但没有一个针对代理机构的多站点工作流提供以下功能：

• 每次编辑前都进行真实备份（有 SSH 时通过 WP-CLI 备份 postmeta，否则回退到 JSON 文件——绝不会悄无声息地丢失）
• 破坏性操作需要两次调用确认（TTL 60s）
• JSON 验证 + 自动回滚，避免编辑生成无效的 Elementor 数据
• 三级 CSS 刷新回退机制（REST → 原生 wp-cli → 删除 option/meta → 重新保存）
• 全局小工具感知——预检会在页面引用共享小工具时发出警告
• WP-CLI 应急通道，用于处理 REST API 无法安全完成的操作
• 通过无头 Chrome 截取屏幕截图（无需 puppeteer 依赖）

---

安装

npx -y elementor-mcp-agent

配置

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"
  }
}]'

请在 https://{your-site}/wp-admin/profile.php#application-passwords-section 生成 WordPress 应用程序密码。

ssh 块为可选项，但启用后可解锁另外 8 个工具（WP-CLI 应急通道 + 可靠的自定义 postmeta 备份）。MCP 无需 SSH 也能运行——备份会保存到本地 JSON 文件。

如果省略 wp_cli_path，系统会自动检测（依次尝试 wp、~/bin/wp.phar 和 ~/wp-cli.phar）。

Claude Desktop 配置

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

---

工具（34 个）

站点与健康状况

• list_sites — 列出站点池
• ping_site — 探测身份验证和版本
• site_health — 多次调用生成健康状况快照

页面

• list_elementor_pages — 处于构建器模式的页面
• read_page_elementor — 解析后的摘要 + 可选的完整树
• list_widgets_in_page — 扁平化的工具清单及摘录
• list_global_widgets — 共享工具（编辑一个 → 会影响每个使用它的页面）
• preflight_check — 验证页面是否适合编辑
• elementor_find_replace — 文本替换，流程为 试运行 → 令牌 → 应用 → 备份 → 验证 → 无效时回滚
• list_elementor_backups / restore_elementor_backup — 完整恢复链，并在恢复前创建安全备份
• duplicate_elementor_page — 在站点内克隆（数据 + page_settings + edit_mode）

模板

• list_elementor_templates — 区分主题构建器与常规库
• export_elementor_template — 可移植 JSON
• import_elementor_template — 导入目标站点
• apply_template_to_page — 将模板数据应用到现有页面

WP-CLI 应急方案（需要 SSH）

• wp_cli_run — 执行任意 wp-cli 命令，并检测破坏性模式 + 要求确认
• wp_search_replace — 执行 wp search-replace，必须先进行试运行
• wp_elementor_flush_css — 三级回退
• wp_plugin_list / wp_plugin_update（需要确认）

视觉

• screenshot_page — 使用无头 Chrome 对任意 URL 截取 PNG
• compare_screenshots — SHA-256 + 字节差异

工具（v1.1 — 工具级 CRUD）

• read_widget — 按 ID 获取单个工具（只读）
• update_widget_settings — 浅层合并设置，并备份 + 验证 + 刷新
• delete_widget — 从父容器中移除工具
• duplicate_widget — 以同级项形式克隆，并生成新 ID
• swap_widget_type — 替换 widgetType + 设置，保留 ID + 位置
• add_widget — 将工具追加到父容器
• move_widget — 在容器之间移动工具（指定位置）

批量与站点集群（v1.1）

• bulk_find_replace_site — 在单个站点的每个 Elementor 页面中查找/替换，并逐页备份 + 验证 + 刷新
• fleet_find_replace — 在站点池中的每个站点执行相同操作（顺序执行，必须先试运行）
• restore_from_file — 从 JSON 文件备份恢复 _elementor_data，并在恢复前创建安全备份

站点集群

• check_elementor_versions — 对照 wordpress.org 最新版本标记过时的安装

---

写入后验证（v1.2）

每个会修改数据的工具都会在写入后从规范 WP 重新读取页面，并向模型呈现持久化状态。HTTP 写入 API 可能会撒谎——即使返回 200 OK，插件筛选器或 REST 异常也可能悄悄丢弃载荷。此约定可让这种情况显现出来。

每个 applied 响应都包含：

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

如果 verification.matches_requested === false，即使 HTTP 层返回 OK，也应视为失败。原始载荷保存在 backup_meta_key 中——可通过 restore_elementor_backup 进行恢复。

---

安全保证

在 src/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

以下 wp-cli 模式无论是否确认，都会被硬性拦截：

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

---

端到端验证

v1.0.0 已在真实环境中通过 Elementor 4.0.9 的在线 WordPress 安装进行测试：

• ✅ 在 v1.0.0 基准版本中，24 个工具里有 21 个通过端到端验证（目前套件已提供 34 个工具 — 参见 工具）
• ✅ find_replace → 备份 → 恢复往返流程可保留数据
• ✅ duplicate_page 会复制数据、page_settings 和 edit_mode
• ✅ apply_template_to_page 支持自动备份
• ✅ wp_cli_run 的破坏性操作流程（删除文章）需要确认
• ✅ 通过 SHA-256 检测截图是否相同
• ✅ 有 SSH 时，CSS 刷新会使用 wp elementor flush-css；否则回退到删除选项的方式

测试中发现的 7 个错误均已修复：

• REST API 会静默丢弃未注册的 postmeta 写入 → 备份改为以 WP-CLI 为主
• 托管主机的 SSH PATH 中没有 wp → 增加自动检测和 wp_cli_path 配置
• SSH 后量子横幅污染 → 添加 stderr 过滤器
• 默认 Kit 被当作“widget”返回 → 添加客户端过滤器
• _elementor_page_settings 的 object/string 类型不匹配 → 进行规范化
• Chrome 冷启动导致截图超时 → 将超时时间延长至 60 秒
• 模板列表存在相同的过滤器错误 → 已修复

---

路线图

v1.1 ✅ 已发布

• Widget 级 CRUD：read_widget、update_widget_settings、delete_widget、duplicate_widget、swap_widget_type、add_widget、move_widget
• bulk_find_replace_site（在一个站点的所有 Elementor 页面中执行）
• fleet_find_replace（在资源池中的所有站点中执行）
• restore_from_file

v1.2

• 全局样式读写
• 跨站点推送 Theme Builder 模板
• 区块/列级操作

v2.0

• 支持 WooCommerce 的工具
• 可视化差异比较（像素比较）
• 定时任务与 cron 调度

---

如果这为你节省了时间

支持该项目最快的方式是在 GitHub 上点个 ⭐ — 这能帮助其他运营 Elementor 站点的代理机构找到它，也能让我了解接下来该开发什么。

你还可以：

• 为错误、边缘情况或缺少的工具提交 issue
• 针对设计或工作流问题发起 discussion
• 分享你用它构建的成果 — 我很乐意了解

许可证

MIT — © 2026 MogaCode。

---

由 Mogacode 开发，该公司是一家提供订阅式服务的搜索引擎优化代理机构：助力网站获得排名。