Elementor MCP

Elementor 기반 WordPress 사이트 작업을 위한 MCP 서버 — 페이지 구조 읽기, 위젯 편집, 글로벌 디자인 토큰 관리, 그리고 아무것도 망가뜨리지 않는 작업.

Elementor는 전체 페이지 레이아웃을 보호된 postmeta 키(_elementor_data)에 JSON 블롭으로 저장합니다. WordPress REST API는 이를 읽거나 쓸 수 없기 때문에, 일반적인 WordPress MCP 서버는 페이지 목록을 나열할 수는 있어도 페이지 내용에는 손댈 수 없습니다. 이 프로젝트는 그 격차를 해소합니다.

제공 기능

• 50개 도구 — 페이지 구조, 요소 수술, 위젯 스키마, 글로벌 디자인, 템플릿, 히스토리 및 사이트 전체 검색.

• 실시간 위젯 스키마. 컨트롤 정의는 대상 사이트 자체의 Elementor 레지스트리에서 읽어오므로, 제공되는 스키마는 해당 사이트에 설치된 위젯(코어, Pro, 서드파티 애드온 팩 포함)을 정확히 설명합니다. 하드코딩된 목록이 아님으로써 낡은 정보가 되지 않습니다.

• 안전한 동시 쓰기. 모든 쓰기 작업은 페이지를 읽을 당시의 콘텐츠 해시를携带하며, 그 사이 페이지가 변경된 경우 거부됩니다. 조용한 덮어쓰기는 없습니다.

• 실행 취소. 모든 쓰기 작업은 먼저 레이아웃을 스냅샷합니다. elementor_restore_snapshot은 마지막 변경을 롤백합니다.

• 원자적 배치. 다단계 구조 변경은 하나의 작업으로 적용되거나 전혀 적용되지 않습니다 — 페이지가 반쯤 편집된 상태로 남는 일은 없습니다.

• 멀티 사이트. 하나의 서버로 여러 WordPress 설치를 관리할 수 있으며, 각각 이름으로 주소를 지정하고 각각 독립적으로 읽기 전용으로 표시할 수 있습니다.

Related MCP server: elementor-mcp-agent

아키텍처

두 부분으로 구성되며, 어느 하나만으로는 작동하지 않습니다:

MCP client  ──stdio──▶  elementor-mcp (Node)  ──REST──▶  WordPress
                                                          ├── Elementor MCP Bridge (this repo)
                                                          └── Elementor

plugin/elementor-mcp-bridge/ — elementor-mcp/v1 REST 네임스페이스를 노출하는 WordPress 플러그인. Elementor 문서를 Elementor 자체의 Document::save()를 통해 읽고 씁니다(에디터가 사용하는 것과 동일한 경로이므로 삭제 처리, 리비전, CSS 재생성이 모두 올바르게 이루어집니다). 또한 실시간 위젯 레지스트리를 검사하여 스키마를 얻습니다.

src/ — MCP 서버. 자체 프로세스에서 요소 트리를 보유하고 구조 작업을 그곳에서 수행하므로, 400KB 페이지도 해당 JSON이 모델의 컨텍스트에 들어가지 않고 편집할 수 있습니다.

이 분할은 의도적입니다. 트리 수술은 TypeScript에 있으며 59개 케이스에 대해 단위 테스트됩니다. PHP 쪽은 얇게 유지되고 Elementor에 위임합니다.

설치

1. 브리지 플러그인

설치 가능한 zip을 빌드하고 wp-admin에서 플러그인 → 새로 추가 → 플러그인 업로드를 통해 업로드합니다:

./scripts/package-plugin.sh
# build/elementor-mcp-bridge-1.0.0.zip

이 스크립트는 어떤 파일이든 php -l에 실패하면 빌드를 거부하므로, 깨진 플러그인은 패키징될 수 없습니다.

또는 직접 설치합니다:

rsync -a plugin/elementor-mcp-bridge/ user@host:/var/www/site/wp-content/plugins/elementor-mcp-bridge/
wp plugin activate elementor-mcp-bridge     # or activate in wp-admin

WordPress 5.9+, PHP 7.4+ 및 Elementor 3.x 또는 4.x가 필요합니다.

실행 중인지 확인합니다:

curl -u 'user:app password' https://example.com/wp-json/elementor-mcp/v1/status

Windows에서 curl은 Invoke-WebRequest의 별칭이며 -u를 허용하지 않습니다. 대신 번들된 진단 도구를 사용하세요. 이 도구는 연결 가능성, REST API, 플러그인 활성화 및 자격 증명을 순서대로 확인하므로 실패 시 어떤 것이 문제인지 알려줍니다:

.\scripts\Test-Bridge.ps1 -SiteUrl https://example.com -Username admin -AppPassword 'abcd efgh ijkl mnop'

또는 별칭 대신 curl.exe로 실제 curl을 강제 사용합니다.

2. 애플리케이션 비밀번호

wp-admin에서 사용자 → 프로필 → 애플리케이션 비밀번호로 이동하여 elementor-mcp라는 이름의 비밀번호를 추가하고 생성된 값을 복사합니다. 이는 계정의 로그인 비밀번호가 아니며 독립적으로 폐기할 수 있습니다.

브리지는 모든 라우트에서 실제 WordPress 권한을 확인하므로, 에이전트는 해당 사용자가 직접 할 수 있는 작업만 수행할 수 있습니다. 사용 사례를 충당하는 최소 역할의 계정을 부여하세요 — 일반적으로 편집자면 충분하며, 사이트 전체 디자인 설정을 변경해야 하는 경우에만 관리자입니다.

3. 서버

npm install
npm run build

구성

단일 사이트:

WORDPRESS_URL=https://example.com
WORDPRESS_USERNAME=your-user
WORDPRESS_APP_PASSWORD="abcd efgh ijkl mnop qrst uvwx"

여러 사이트 — ELEMENTOR_MCP_SITES를 JSON 배열로 설정:

[
  { "name": "live",    "url": "https://example.com",         "username": "u", "appPassword": "..." },
  { "name": "staging", "url": "https://staging.example.com", "username": "u", "appPassword": "...", "readOnly": true }
]

클라이언트 연결

Claude Code:

claude mcp add elementor -- node /path/to/elementor-mcp/dist/index.js

또는 MCP 클라이언트 구성을 직접 편집:

{
  "mcpServers": {
    "elementor": {
      "command": "node",
      "args": ["/path/to/elementor-mcp/dist/index.js"],
      "env": {
        "WORDPRESS_URL": "https://example.com",
        "WORDPRESS_USERNAME": "your-user",
        "WORDPRESS_APP_PASSWORD": "abcd efgh ijkl mnop qrst uvwx"
      }
    }
  }
}

효과적인 사용법

도구 설명이 이를 지향하지만, 간단히 요약하면:

1. 사이트당 한 번 elementor_site_status — 버전, 위젯 수, 인증된 사용자가 할 수 있는 작업.

2. elementor_get_outline으로 요소 ID를 얻습니다. 정말로 모든 설정이 필요하지 않다면 elementor_get_page_tree를 사용하지 마세요. 아웃라인은 크기의 일부에 불과합니다.

3. 익숙하지 않은 위젯 설정을 지정하기 전에 elementor_get_widget_schema. 컨트롤 이름은 추측할 수 없으며, 잘못된 키는 눈에 보이는 효과 없이 조용히 저장됩니다 — 이는 Elementor 자동화가 잘못되는 가장 흔한 방식입니다.

4. 다단계 작업에는 elementor_batch_edit.

5. 결과 확인은 elementor_render_page.

반응형 설정은 _tablet 및 _mobile 접미사를 사용합니다(padding, padding_tablet, padding_mobile). 스키마는 어떤 컨트롤이 반응형인지 표시하고 정확한 키를 명시합니다.

안전 모델

영구 삭제 및 커밋된 사이트 전체 교체를 허용하려면 wp-config.php에 추가:

define( 'EMCP_ALLOW_DESTRUCTIVE', true );

도구

전체 참조는 docs/TOOLS.md에 있습니다. 영역별:

• 사이트 — elementor_list_sites, elementor_site_status, elementor_native_mcp_call

• 페이지 — 목록, 가져오기, 아웃라인, 생성, 복제, 삭제, 렌더링, 메타데이터 업데이트, 전체 트리

• 요소 — 가져오기, 찾기, 위젯 추가, 컨테이너 추가, 업데이트, 이동, 복제, 삭제, 재정렬, 래핑, 배치 편집, 트리 교체

• 위젯 — 목록, 스키마, 요소 유형, 동적 태그

• 디자인 — 글로벌, 글로벌 색상 설정, 글로벌 업데이트, 사용자 정의 CSS, 글로벌 클래스, CSS 플러시

• 템플릿 — 목록, 가져오기, 저장, 적용, 내보내기, 가져오기

• 히스토리 — 스냅샷(목록/생성/복원), 리비전(목록/복원)

• 콘텐츠 — 검색, 찾기 및 바꾸기, 위젯 사용량, 미디어 목록, 이미지 업로드

Elementor 자체 MCP 모듈

Elementor 4.3에는 내장 MCP 모듈이 포함되어 있으며, WordPress Abilities API 뒤에 게이트되고 v4 원자적 기능(글로벌 클래스, 변수, 컴포넌트, 컴포지션)에 초점을 맞춥니다. 이 모듈이 있는 경우 elementor_native_mcp_call은 해당 모듈로 직접 프록시하므로, 여기의 모든 기능과 함께 해당 기능도 사용할 수 있습니다.

이 모듈은 이 서버의 대체품이 아닙니다: Elementor 4.3+와 선택적 종속성 설치가 필요하며, 현재 운영 중인 대다수 Elementor 사이트가 기반으로 하는 클래식 섹션/컬럼/위젯 모델을 다루지 않습니다. elementor_site_status는 이 모듈의 사용 가능 여부를 보고합니다.

개발

npm run build            # compile
npm test                 # 59 unit tests
npm run typecheck        # source and tests
npm run smoke            # boot the server and exercise the MCP handshake
npm run docs             # regenerate docs/TOOLS.md from the running server
php tests/plugin-load.php   # load the plugin and register all 32 routes
./scripts/package-plugin.sh # build the installable zip

tests/plugin-load.php는 스텁된 WordPress 함수에 대해 브리지를 로드하고 모든 라우트에 호출 가능한 핸들러와 권한 콜백이 있는지 확인합니다. 실제 사이트를 대체하지는 않지만, zip이 업로드될 때까지 숨겨져 있을 활성화 치명적 오류를 잡아냅니다.

라이선스

MIT. LICENSE 참조.