内容
# elementor-mcp-agent
[](https://www.npmjs.com/package/elementor-mcp-agent)
[](./LICENSE)
[](https://glama.ai/mcp/servers/Mogacode-ma/elementor-mcp-agent)
[](https://github.com/Mogacode-ma/elementor-mcp-agent/stargazers)
> **适用于 WordPress Elementor 的专业级 MCP 服务器。** 多站点管理，安全的 Elementor 编辑，备份 + 自动回滚 + CSS 刷新，模板导出/导入，全局小部件检测，截图，WP-CLI 逃生口。
为运行多个 Elementor / Elementor Pro 客户端网站的机构而构建，这些机构希望 Claude（或任何 MCP 客户端）能够驱动工作量 —— **而不会破坏页面**。
---
## 本项目构建过程
elementor-mcp-agent 从头到尾使用 Claude Code 构建，耗时约 48 小时。该过程是故意公开的：
- 架构、代码、测试、文档 —— 所有内容都通过 Claude Code 结对编程会话生成
- 在针对实时 WordPress + Elementor 安装的实时 E2E 测试中发现了 [此事后分析](https://dev.to/mogacode/7-bugs-i-caught-in-my-mcp-server-before-publishing-and-why-i-almost-shipped-a-data-corruption-5dfd) 中记录的 7 个错误
- v1.2 的写入后验证模式在读者评论后 2 小时内发布（[Dev.to 上的 Mads Hansen](https://dev.to/mogacode/7-bugs-i-caught-in-my-mcp-server-before-publishing-and-why-i-almost-shipped-a-data-corruption-5dfd/comments)）—— 更新日志记录了来源
这不是通过墙扔过来的 vibe-coded 软件。每个版本都经过了 lint + 类型检查 + 27 个单元测试 +（对于 v1.0）完整的 E2E 真实 WordPress 安装测试后才发布。MCP 本身硬编码了防护措施，防止模型发出破坏性的 WP-CLI 调用。
我经营一个小型 WordPress 机构，每天在客户端网站上使用此工具。如果您对生产基础设施的代理代码生成持怀疑态度，整个提交历史都是公开的 —— 自己判断。
---
## 为什么存在该项目
今天 GitHub 上有 25+ 个 WordPress MCP 服务器。没有一个针对 **机构多站点工作流**，具备：
- **每次编辑前实时备份**（当 SSH 可用时通过 WP-CLI，当 SSH 不可用时通过 JSON 文件备份 —— 永远不会丢失）
- **任何破坏性操作的两次确认**（TTL 60s）
- **JSON 验证 + 自动回滚**，如果编辑生成无效的 Elementor 数据
- **3 级 CSS 刷新回退**（REST → wp-cli 原生 → 选项/元删除 → 重新保存）
- **全局小部件感知** —— 预检检查警告如果页面引用共享小部件
- **WP-CLI 逃生口**，适用于 REST API 无法安全执行的所有操作
- **截图**，通过无头 Chrome（无 puppeteer 依赖）
---
## 安装
```bash
npx -y elementor-mcp-agent
```
## 配置
```bash
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 逃生口 + 可靠的自定义元备份）。MCP 在没有 SSH 的情况下工作，备份转而保存到本地 JSON 文件中。
如果省略 `wp_cli_path`，则会自动检测（尝试 `wp`，然后 `~/bin/wp.phar`，然后 `~/wp-cli.phar`）。
### Claude Desktop 配置
```json
{
"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` —— 文本替换，**dry-run → token → apply → backup → validate → rollback if invalid**
- `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`，强制 dry-run
- `wp_elementor_flush_css` —— 3 级回退
- `wp_plugin_list` / `wp_plugin_update`（带有确认）
### 视觉
- `screenshot_page` —— 任意 URL 的无头 Chrome PNG
- `compare_screenshots` —— SHA-256 + 字节增量
### 小部件（v1.1 —— 小部件级 CRUD）
- `read_widget` —— 按 ID 读取小部件（只读）
- `update_widget_settings` —— 浅合并设置，带有备份 + 验证 + 刷新
- `delete_widget` —— 从父容器中删除小部件
- `duplicate_widget` —— 克隆为兄弟节点，带有新鲜 ID
- `swap_widget_type` —— 替换小部件类型 + 设置，保留 ID + 位置
- `add_widget` —— 将小部件追加到父容器中
- `move_widget` —— 在容器之间移动小部件（带有位置）
### 批量和舰队（v1.1）
- `bulk_find_replace_site` —— 在一个站点的所有 Elementor 页面上查找/替换，每个页面备份 + 验证 + 刷新
- `fleet_find_replace` —— 在所有站点上执行相同的操作（顺序，强制 dry-run）
- `restore_from_file` —— 从 JSON 文件备份中恢复 `_elementor_data`，带有预恢复安全备份
### 舰队
- `check_elementor_versions` —— 标记过时的安装程序与 wordpress.org 最新版本不符
---
## 写入后验证（v1.2）
每个变异小部件工具都会在写入 **之后** 从规范的 WP 读取页面，并将持久状态显示给模型。HTTP 编写 API 可以撒谎 —— 返回 200 OK 而插件过滤器或 REST 怪癖会静默删除负载。这使得该问题可观察。
每个 `applied` 响应都包含：
```jsonc
{
"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` 中硬编码：
```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 安装中进行了测试：
- ✅ 21/24 个工具端到端验证
- ✅ find_replace → backup → restore 循环保存数据
- ✅ duplicate_page 复制数据 + page_settings + edit_mode
- ✅ apply_template_to_page 带有自动备份
- ✅ wp_cli_run 破坏性流程（发布后删除）需要确认
- ✅ 截图通过 SHA-256 检测相同
- ✅ CSS 刷新使用 `wp elementor flush-css`（当 SSH 可用时），否则回退到选项删除
测试期间发现了 7 个错误，所有错误都已修复：
- REST API 静默删除未注册的 postmeta 写入 → 切换到 WP-CLI 主要用于备份
- 在托管主机上 `wp` 未在 SSH PATH 中 → 自动检测 + `wp_cli_path` 配置
- SSH 后量子横幅污染 → stderr 过滤器
- 默认套件作为“小部件”返回 → 客户端过滤器
- `_elementor_page_settings` 类型对象/字符串不匹配 → 规范化
- Chrome 冷启动截图超时 → 增加到 60 秒
- 模板列表相同筛选错误 → 已修复
---
## 路线图
**v1.1** ✅ 已发布
- 小部件级 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**
- 全局样式读取/写入
- 主题构建器模板推送到多个站点
- 部分/列级操作
**v2.0**
- WooCommerce 感知工具
- 视觉差异（像素比较）
- 调度 + cron 调度
---
## 如果这为您节省了时间
支持该项目的最快方式是在 GitHub 上 **加星** —— 它帮助其他运行 Elementor 站点的机构找到该项目，并告诉我应该继续构建什么。
您还可以：
- 打开一个 [问题](https://github.com/Mogacode-ma/elementor-mcp-agent/issues) 来报告错误、边缘情况或缺失的工具
- 启动一个 [讨论](https://github.com/Mogacode-ma/elementor-mcp-agent/discussions) 来讨论设计或工作流问题
- 分享您使用它构建的内容 —— 我很乐意听到
## 许可证
[MIT](./LICENSE) —— 2026 [MogaCode](https://mogacode.ma)。
