elementor-mcp-agent

Servidor MCP de nível profissional para WordPress Elementor — gerenciamento de frota multi-site, edição segura em nível de página/widget, exportação/importação de modelos, rastreamento de versões com snapshot/rollback.

GitHub
3
Experimente este MCPPatrocinado

Documentação

elementor-mcp-agent

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

Servidor MCP de nível agência para WordPress Elementor. Gerenciamento multi-site, edições seguras do Elementor com backup + rollback automático + limpeza de CSS, exportação/importação de templates, detecção de widgets globais, capturas de tela, saída de emergência via WP-CLI.

Construído para agências que gerenciam muitos sites de clientes em Elementor / Elementor Pro e querem que o Claude (ou qualquer cliente MCP) assuma o trabalho braçal — sem quebrar páginas.

Como isso foi construído

O elementor-mcp-agent foi construído de ponta a ponta com o Claude Code em cerca de 48 horas. O processo é intencionalmente aberto:

  • Arquitetura, código, testes, documentação — tudo gerado em sessões de pair-programming com o Claude Code
  • Os 7 bugs documentados em este post-mortem foram capturados em testes E2E reais contra uma instalação ao vivo de WordPress + Elementor, não depois do fato
  • O padrão de verificação pós-escrita da v1.2 foi lançado 2 horas após um comentário de leitor (Mads Hansen no Dev.to) — o changelog credita a fonte

Isso não é software "vibe-coded" jogado por cima do muro. Cada versão passou por lint + typecheck + 27 testes unitários + (para v1.0) E2E completo contra uma instalação real de WordPress antes da publicação. O próprio MCP tem guardrails embutidos que impedem o modelo de fazer chamadas destrutivas ao WP-CLI.

Eu administro uma pequena agência de WordPress e uso esta ferramenta todos os dias em sites de clientes. Se você é cético sobre codegen agêntico para infraestrutura de produção, todo o histórico de commits está aberto — julgue por si mesmo.

Por que isso existe

Existem mais de 25 servidores MCP de WordPress no GitHub hoje. Nenhum atende ao fluxo de trabalho multi-site para agências com:

  • Backup real antes de cada edição (postmeta via WP-CLI quando SSH está disponível, fallback para arquivo JSON — nunca perdido silenciosamente)
  • Confirmação em duas chamadas para qualquer operação destrutiva (TTL 60s)
  • Validação JSON + rollback automático se uma edição produzir dados inválidos do Elementor
  • Fallback de limpeza de CSS em 3 níveis (REST → wp-cli nativo → exclusão de option/meta → re-salvar)
  • Consciência de widgets globais — verificação prévia avisa se uma página referencia widgets compartilhados
  • Saída de emergência via WP-CLI para tudo que a API REST não pode fazer com segurança
  • Capturas de tela via Chrome headless (sem dependência de puppeteer)

Instalação

npx -y elementor-mcp-agent

Configuração

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

Gere a Senha de Aplicativo do WordPress em https://{your-site}/wp-admin/profile.php#application-passwords-section.

O bloco ssh é opcional, mas desbloqueia 8 ferramentas adicionais (saída de emergência via WP-CLI + backups confiáveis de postmeta personalizado). O MCP funciona sem SSH — os backups vão para arquivos JSON locais.

wp_cli_path é auto-detectado se omitido (tenta wp, depois ~/bin/wp.phar, depois ~/wp-cli.phar).

Configuração do 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\":\"...\"}]"
      }
    }
  }
}

Ferramentas (34)

Sites e saúde

  • list_sites — enumerar o pool
  • ping_site — sonda de autenticação + versão
  • site_health — snapshot de saúde com múltiplas chamadas

Páginas

  • list_elementor_pages — páginas em modo construtor
  • read_page_elementor — resumo analisado + árvore completa opcional
  • list_widgets_in_page — inventário plano de widgets com trechos
  • list_global_widgets — widgets compartilhados (editar um → afeta todas as páginas que o usam)
  • preflight_check — validar se uma página é segura para editar
  • elementor_find_replace — substituição de texto com dry-run → token → aplicar → backup → validar → rollback se inválido
  • list_elementor_backups / restore_elementor_backup — cadeia completa de restauração com backup de segurança pré-restauração
  • duplicate_elementor_page — clonar dentro de um site (data + page_settings + edit_mode)

Templates

  • list_elementor_templates — Theme Builder distinguido da biblioteca regular
  • export_elementor_template — JSON portátil
  • import_elementor_template — inserir no site de destino
  • apply_template_to_page — empurrar dados de template para uma página existente

Saída de emergência via WP-CLI (requer SSH)

  • wp_cli_run — comando wp-cli arbitrário com detecção de padrões destrutivos + confirmação
  • wp_search_replace — wp search-replace com dry-run obrigatório
  • wp_elementor_flush_css — fallback em 3 níveis
  • wp_plugin_list / wp_plugin_update (com confirmação)

Visual

  • screenshot_page — PNG via Chrome headless de qualquer URL
  • compare_screenshots — SHA-256 + delta de bytes

Widgets (v1.1 — CRUD em nível de widget)

  • read_widget — buscar um widget por id (somente leitura)
  • update_widget_settings — mesclagem superficial de configurações, com backup + validação + limpeza
  • delete_widget — remover um widget do contêiner pai
  • duplicate_widget — clonar como irmão com novo id
  • swap_widget_type — substituir widgetType + configurações, preservar id + posição
  • add_widget — anexar um widget a um contêiner pai
  • move_widget — mover um widget entre contêineres (com posição)

Em massa e frota (v1.1)

  • bulk_find_replace_site — localizar/substituir em todas as páginas Elementor de um site, com backup por página + validação + limpeza
  • fleet_find_replace — o mesmo em todos os sites do pool (sequencial, dry-run obrigatório)
  • restore_from_file — restaurar _elementor_data a partir de um backup em arquivo JSON, com backup de segurança pré-restauração

Frota

  • check_elementor_versions — sinalizar instalações desatualizadas em relação ao wordpress.org mais recente

Verificação pós-escrita (v1.2)

Toda ferramenta de mutação de widget relê a página do WP canônico após a escrita e expõe o estado persistido ao modelo. A API de escrita HTTP pode mentir — retornar 200 OK enquanto filtros de plugin ou peculiaridades do REST descartam silenciosamente o payload. Este contrato torna isso observável.

Toda resposta de applied carrega:

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

Se verification.matches_requested === false, trate como falha mesmo que a camada HTTP tenha dito OK. O payload original sobrevive em backup_meta_key — restaure via restore_elementor_backup.

Garantias de segurança

Embutidos em 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

E estes padrões de wp-cli são bloqueados à força independentemente de confirmação:

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

Verificado de ponta a ponta

A v1.0.0 foi testada em condições reais contra uma instalação ao vivo de WordPress com Elementor 4.0.9:

  • ✅ 21/24 ferramentas validadas de ponta a ponta na linha de base v1.0.0 (a suíte agora expõe 34 — veja Ferramentas)
  • ✅ find_replace → backup → restauração preserva dados
  • ✅ duplicate_page copia data + page_settings + edit_mode
  • ✅ apply_template_to_page com backup automático
  • ✅ fluxo destrutivo do wp_cli_run (exclusão de post) requer confirmação
  • ✅ detecção de capturas de tela idênticas via SHA-256
  • ✅ limpeza de CSS usa wp elementor flush-css quando SSH está disponível, cai para exclusão de option caso contrário

7 bugs encontrados durante os testes, todos corrigidos:

  • A API REST descarta silenciosamente escritas de postmeta não registradas → mudou para WP-CLI como principal para backups
  • wp não está no PATH do SSH em hosts gerenciados → auto-detecção + configuração wp_cli_path
  • Poluição de banner pós-quântico do SSH → filtro de stderr
  • Kit padrão retornado como "widget" → filtro no lado do cliente
  • Incompatibilidade de tipo object/string em _elementor_page_settings → normalização
  • Timeout de captura de tela no cold-start do Chrome → aumentado para 60s
  • Bug de filtro na listagem de templates → corrigido

Roadmap

v1.1 ✅ lançada

  • CRUD em nível de widget: read_widget, update_widget_settings, delete_widget, duplicate_widget, swap_widget_type, add_widget, move_widget
  • bulk_find_replace_site (em todas as páginas Elementor de um site)
  • fleet_find_replace (em todos os sites do pool)
  • restore_from_file

v1.2

  • Leitura/escrita de estilos globais
  • Envio de templates do Theme Builder entre sites
  • Operações em nível de seção/coluna

v2.0

  • Ferramentas com consciência WooCommerce
  • Diff visual (comparação de pixels)
  • Agendamento + cron

Se isso economizou seu tempo

A forma mais rápida de apoiar o projeto é um ⭐ star no GitHub — ajuda outras agências que gerenciam sites Elementor a encontrar isto e me diz o que continuar construindo.

Você também pode:

  • Abrir uma issue para bugs, casos extremos ou ferramentas ausentes
  • Iniciar uma discussão para dúvidas de design ou fluxo de trabalho
  • Compartilhar o que você construiu com isso — adoraria saber

Licença

MIT — © 2026 MogaCode.