elementor-mcp-agent

Servidor MCP de nivel profesional para WordPress Elementor: gestión de flotas multi-sitio, edición segura a nivel de página/widget, exportación/importación de plantillas, seguimiento de versiones con instantáneas y reversión.

GitHub
3
Prueba este MCPPatrocinado

Documentación

elementor-mcp-agent

npm version License: MIT Mogacode-ma/elementor-mcp-agent MCP server GitHub stars

Servidor MCP de nivel agencia para WordPress Elementor. Gestión multi-sitio, ediciones seguras de Elementor con respaldo + reversión automática + limpieza de CSS, exportación/importación de plantillas, detección de widgets globales, capturas de pantalla, vía de escape WP-CLI.

Construido para agencias que gestionan muchos sitios de clientes con Elementor / Elementor Pro y quieren que Claude (o cualquier cliente MCP) maneje el trabajo pesado — sin romper páginas.

Cómo se construyó esto

elementor-mcp-agent se construyó de principio a fin con Claude Code en aproximadamente 48 horas. El proceso es intencionalmente abierto:

  • Arquitectura, código, pruebas, documentación — todo generado mediante sesiones de programación en pareja con Claude Code
  • Los 7 errores documentados en esta autopsia se detectaron en pruebas E2E reales contra una instalación en vivo de WordPress + Elementor, no después del hecho
  • El patrón de verificación posterior a la escritura de v1.2 se publicó 2 horas después del comentario de un lector (Mads Hansen en Dev.to) — el registro de cambios acredita la fuente

Esto no es software generado al azar y lanzado sin más. Cada versión pasó por lint + typecheck + 27 pruebas unitarias + (para v1.0) E2E completo contra una instalación real de WordPress antes de publicarse. El propio MCP incorpora protecciones que impiden que el modelo realice llamadas destructivas de WP-CLI.

Dirijo una pequeña agencia de WordPress y uso esta herramienta a diario en sitios de clientes. Si eres escéptico sobre la generación de código agéntico para infraestructura de producción, todo el historial de commits está abierto — juzga por ti mismo.

Por qué existe esto

Hoy hay más de 25 servidores MCP de WordPress en GitHub. Ninguno apunta al flujo de trabajo multi-sitio de agencia con:

  • Respaldo real antes de cada edición (postmeta vía WP-CLI cuando SSH está disponible, respaldo en archivo JSON como alternativa — nunca se pierde silenciosamente)
  • Confirmación de dos llamadas para cualquier operación destructiva (TTL 60s)
  • Validación JSON + reversión automática si una edición produce datos de Elementor inválidos
  • Respaldo de limpieza de CSS de 3 niveles (REST → wp-cli nativo → eliminación de opción/meta → re-guardado)
  • Conciencia de widgets globales — la verificación previa advierte si una página referencia widgets compartidos
  • Vía de escape WP-CLI para todo lo que la API REST no puede hacer de forma segura
  • Capturas de pantalla mediante Chrome sin interfaz (sin dependencia de puppeteer)

Instalación

npx -y elementor-mcp-agent

Configuración

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

Genera la Contraseña de Aplicación de WordPress en https://{your-site}/wp-admin/profile.php#application-passwords-section.

El bloque ssh es opcional pero desbloquea 8 herramientas adicionales (vía de escape WP-CLI + respaldos confiables de postmeta personalizados). El MCP funciona sin SSH — los respaldos van a archivos JSON locales en su lugar.

wp_cli_path se auto-detecta si se omite (prueba wp, luego ~/bin/wp.phar, luego ~/wp-cli.phar).

Configuración de 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\":\"...\"}]"
      }
    }
  }
}

Herramientas (34)

Sitios y salud

  • list_sites — enumerar el grupo
  • ping_site — autenticación + prueba de versión
  • site_health — instantánea de salud de múltiples llamadas

Páginas

  • list_elementor_pages — páginas en modo constructor
  • read_page_elementor — resumen analizado + árbol completo opcional
  • list_widgets_in_page — inventario plano de widgets con extractos
  • list_global_widgets — widgets compartidos (editar uno → afecta a cada página que lo usa)
  • preflight_check — validar que una página es segura de editar
  • elementor_find_replace — reemplazo de texto con prueba en seco → token → aplicar → respaldo → validar → revertir si es inválido
  • list_elementor_backups / restore_elementor_backup — cadena completa de restauración con respaldo de seguridad previo a la restauración
  • duplicate_elementor_page — clonar dentro de un sitio (datos + page_settings + edit_mode)

Plantillas

  • list_elementor_templates — Theme Builder distinguido de la biblioteca regular
  • export_elementor_template — JSON portátil
  • import_elementor_template — insertar en el sitio de destino
  • apply_template_to_page — empujar datos de plantilla a una página existente

Vía de escape WP-CLI (requiere SSH)

  • wp_cli_run — comando wp-cli arbitrario con detección de patrones destructivos + confirmación
  • wp_search_replace — wp search-replace con prueba en seco obligatoria
  • wp_elementor_flush_css — respaldo de 3 niveles
  • wp_plugin_list / wp_plugin_update (con confirmación)

Visual

  • screenshot_page — PNG de Chrome sin interfaz de cualquier URL
  • compare_screenshots — SHA-256 + delta de bytes

Widgets (v1.1 — CRUD a nivel de widget)

  • read_widget — obtener un widget por id (solo lectura)
  • update_widget_settings — fusión superficial de configuraciones, con respaldo + validación + limpieza
  • delete_widget — eliminar un widget de su contenedor padre
  • duplicate_widget — clonar como hermano con id nuevo
  • swap_widget_type — reemplazar widgetType + configuraciones, preservar id + posición
  • add_widget — añadir un widget a un contenedor padre
  • move_widget — mover un widget entre contenedores (con posición)

Lote y flota (v1.1)

  • bulk_find_replace_site — buscar/reemplazar en cada página de Elementor de un sitio, respaldo por página + validación + limpieza
  • fleet_find_replace — lo mismo en cada sitio del grupo (secuencial, prueba en seco obligatoria)
  • restore_from_file — restaurar _elementor_data desde un respaldo de archivo JSON, con respaldo de seguridad previo a la restauración

Flota

  • check_elementor_versions — marcar instalaciones desactualizadas contra la última versión de wordpress.org

Verificación posterior a la escritura (v1.2)

Cada herramienta de mutación de widgets vuelve a leer la página desde el WP canónico después de la escritura y muestra el estado persistido al modelo. La API de escritura HTTP puede mentir — devolver 200 OK mientras los filtros de plugins o peculiaridades de REST eliminan silenciosamente el payload. Este contrato hace que eso sea observable.

Cada respuesta de applied lleva:

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

Si verification.matches_requested === false, trátalo como un fallo incluso si la capa HTTP dijo OK. El payload original sobrevive en backup_meta_key — restaura vía restore_elementor_backup.

Garantías de seguridad

Codificado en 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

Y estos patrones de wp-cli están bloqueados por completo independientemente de la confirmación:

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

Verificado de extremo a extremo

v1.0.0 se probó en condiciones reales contra una instalación en vivo de WordPress con Elementor 4.0.9:

  • ✅ 21/24 herramientas validadas de extremo a extremo en la línea base v1.0.0 (el conjunto ahora expone 34 — ver Herramientas)
  • ✅ El ciclo find_replace → respaldo → restauración preserva los datos
  • ✅ duplicate_page copia datos + page_settings + edit_mode
  • ✅ apply_template_to_page con respaldo automático
  • ✅ Flujo destructivo de wp_cli_run (eliminación de post) requiere confirmación
  • ✅ Detección idéntica de capturas de pantalla vía SHA-256
  • ✅ La limpieza de CSS usa wp elementor flush-css cuando SSH está disponible, y recurre a la eliminación de opciones en caso contrario

7 errores encontrados durante las pruebas, todos corregidos:

  • La API REST elimina silenciosamente escrituras de postmeta no registradas → se cambió a WP-CLI como principal para respaldos
  • wp no está en el PATH de SSH en hosts gestionados → auto-detección + configuración de wp_cli_path
  • Contaminación del banner post-cuántico de SSH → filtro de stderr
  • Kit predeterminado devuelto como "widget" → filtro del lado del cliente
  • Desajuste de tipo objeto/cadena de _elementor_page_settings → normalización
  • Tiempo de espera de captura de pantalla en arranque en frío de Chrome → aumentado a 60s
  • Mismo error de filtro en listado de plantillas → corregido

Hoja de ruta

v1.1 ✅ publicado

  • CRUD a nivel de widget: read_widget, update_widget_settings, delete_widget, duplicate_widget, swap_widget_type, add_widget, move_widget
  • bulk_find_replace_site (en todas las páginas de Elementor de un sitio)
  • fleet_find_replace (en todos los sitios del grupo)
  • restore_from_file

v1.2

  • Lectura/escritura de estilos globales
  • Empuje de plantillas de Theme Builder entre sitios
  • Operaciones a nivel de sección/columna

v2.0

  • Herramientas conscientes de WooCommerce
  • Diff visual (comparación de píxeles)
  • Programación + programación cron

Si esto te ahorró tiempo

La forma más rápida de apoyar el proyecto es una ⭐ estrella en GitHub — ayuda a que otras agencias que gestionan sitios de Elementor lo encuentren y me dice qué seguir construyendo.

También puedes:

  • Abrir un issue para errores, casos límite o herramientas faltantes
  • Iniciar una discusión para preguntas de diseño o flujo de trabajo
  • Compartir lo que construiste con ello — me encantaría escucharlo

Licencia

MIT — © 2026 MogaCode.