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 環境での E2E テスト中に発見されました
• v1.2 の書き込み後検証パターンは、読者のコメントから 2 時間後にリリースされました（Dev.to の Mads Hansen）。変更履歴には提供元が記載されています

これは、AI に任せて作ったソフトウェアを放置したものではありません。リリースのたびに、公開前に lint、型チェック、27 件のユニットテストを実施し、（v1.0 では）実際の WordPress 環境で完全な E2E テストを行いました。MCP 自体にも、モデルによる破壊的な WP-CLI 呼び出しを防ぐガードレールがハードコードされています。

私は小規模な WordPress 制作会社を運営しており、クライアントのサイトでこのツールを毎日使っています。本番インフラにおけるエージェント型コード生成に懐疑的な方は、コミット履歴をすべて公開しているので、ご自身でご判断ください。

---

開発の背景

現在、GitHub には WordPress 向け MCP サーバーが 25 個以上あります。制作会社の複数サイト運用ワークフローを対象に、次の機能を備えたものはありません。

• 編集前に毎回、実際のバックアップを作成（SSH が利用できる場合は WP-CLI で postmeta をバックアップ。利用できない場合は JSON ファイルにフォールバックし、データを黙って失うことはありません）
• 破壊的な操作には2 回の呼び出しによる確認を実施（TTL 60 秒）
• 編集によって無効な Elementor データが生成された場合、JSON を検証して自動ロールバック
• 3 段階の CSS フラッシュのフォールバック（REST → wp-cli ネイティブ → option/meta の削除 → 再保存）
• グローバルウィジェットを認識 — ページが共有ウィジェットを参照している場合、事前チェックで警告します
• REST API で安全に実行できない操作に対応するWP-CLI の代替手段
• ヘッドレス 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"
  }
}]'

WordPress アプリケーションパスワードは、https://{your-site}/wp-admin/profile.php#application-passwords-section で生成します。

ssh ブロックは任意ですが、有効にすると8 つの追加ツール（WP-CLI の代替手段＋信頼性の高いカスタム postmeta バックアップ）が利用できます。SSH なしでも MCP は動作し、バックアップはローカルの 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 — 共有ウィジェット（1つを編集すると、それを使用するすべてのページに影響します）
• preflight_check — ページが安全に編集できるかを検証
• elementor_find_replace — テキスト置換。ドライラン → トークン → 適用 → バックアップ → 検証 → 無効な場合はロールバック
• list_elementor_backups / restore_elementor_backup — 復元前の安全バックアップを含む完全な復元チェーン
• duplicate_elementor_page — サイト内で複製（data + 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 — 3 段階のフォールバック
• wp_plugin_list / wp_plugin_update（確認を伴う）

ビジュアル

• screenshot_page — 任意の URL のヘッドレス Chrome PNG
• compare_screenshots — SHA-256 ＋バイト差分

ウィジェット（v1.1 — ウィジェット単位の CRUD）

• read_widget — ID でウィジェットを 1 つ取得（読み取り専用）
• update_widget_settings — バックアップ＋検証＋フラッシュを伴う、設定の浅いマージ
• delete_widget — 親コンテナからウィジェットを削除
• duplicate_widget — 新しい ID で兄弟ウィジェットとして複製
• swap_widget_type — ID と位置を保持して widgetType ＋設定を置換
• add_widget — 親コンテナにウィジェットを追加
• move_widget — 位置を指定してウィジェットをコンテナ間で移動

一括処理とフリート（v1.1）

• bulk_find_replace_site — 1 つのサイトのすべての Elementor ページで検索／置換。ページごとのバックアップ＋検証＋フラッシュを実行
• fleet_find_replace — プール内のすべてのサイトで同様の処理を実行（順次実行、ドライラン必須）
• restore_from_file — JSON ファイルのバックアップから _elementor_data を復元。復元前の安全バックアップを作成

フリート

• check_elementor_versions — wordpress.org の最新版と照らし合わせて、古いインストールを検出

---

書き込み後の検証（v1.2）

変更を行うすべてのウィジェットツールは、書き込み後に正規の WP からページを再読み込みし、永続化された状態をモデルに提示します。HTTP 書き込み API は、プラグインのフィルターや REST の仕様上の問題によってペイロードをひそかに破棄しながら、200 OK を返すことがあります。この仕様により、その状態を確認できます。

すべての 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 → backup → restore の一連の処理でデータが保持されることを確認
• ✅ duplicate_page でデータ + page_settings + edit_mode がコピーされることを確認
• ✅ auto-backup を使用した apply_template_to_page
• ✅ wp_cli_run の破壊的な処理（投稿の削除）には確認が必要
• ✅ SHA-256によるスクリーンショットの一致検出
• ✅ CSSのフラッシュでは、SSHが使用可能な場合は wp elementor flush-css を使い、それ以外の場合はオプションの削除にフォールバック

テスト中に7件のバグが見つかりましたが、すべて修正済みです。

• REST APIが登録されていないpostmetaへの書き込みを通知なく破棄 → バックアップではWP-CLIを優先するよう変更
• 管理ホストのSSH PATHに wp がない → 自動検出と wp_cli_path 設定を追加
• SSHのポスト量子暗号バナーによる出力の混入 → stderrフィルターを追加
• Default Kitが「widget」として返される → クライアント側のフィルターを追加
• _elementor_page_settings の型がobject/stringで不一致 → 正規化
• 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（1つのサイトにあるすべてのElementorページを対象）
• fleet_find_replace（プール内のすべてのサイトを対象）
• restore_from_file

v1.2

• グローバルスタイルの読み取り／書き込み
• 複数サイトへのTheme Builderテンプレートの適用
• セクション／カラム単位の操作

v2.0

• WooCommerce対応ツール
• ビジュアル差分（ピクセル比較）
• スケジュール設定とcronによるスケジューリング

---

役に立った場合

このプロジェクトを支援する最も手軽な方法は、GitHubで⭐を付けることです。Elementorサイトを運営するほかのエージェンシーがこのプロジェクトを見つけやすくなり、今後の開発に役立てることができます。

ほかにも、次の方法で参加できます。

• バグ、特殊なケース、不足しているツールについてissueを作成する
• 設計やワークフローに関する質問をディスカッションで始める
• このプロジェクトを使って作ったものを共有する — ぜひお聞かせください

ライセンス

MIT — © 2026 MogaCode。

---

Mogacodeが開発。サブスクリプション型のSEOエージェンシーです：検索順位を獲得するサイト。