WordPress MCP 어댑터: Claude Code 및 Cursor를 사이트에 연결하기

WordPress MCP Adapter는 Claude Code나 Cursor 같은 AI 도구가 WordPress 사이트에서 동작을 찾고 실행할 수 있게 해줍니다. 이 어댑터는 Abilities API로 등록한 기능을 Model Context Protocol (MCP)을 통해 공유합니다.

전체 설정 방법은 다음과 같습니다: 어댑터를 설치하고, 하나의 기능을 노출하며, 기본 엔드포인트를 찾고, 애플리케이션 비밀번호(Application Password)로 로그인한 다음, 몇 가지 안전 점검을 수행합니다.

이미 AI 도구를 WordPress 사이트에 연결해 보셨나요? 끝으로 건너뛰어 어떻게 되었는지 알려주세요. 제가 기록을 비교하고 싶습니다.

한눈에 보기

필수 조건: WordPress 6.9 이상 및 PHP 7.4 이상. WordPress 6.9에는 Abilities API가 코어에 포함되어 있습니다.
플러그인: WordPress GitHub 조직의 공식 MCP Adapter입니다. 제가 이 가이드를 작성했을 때 최신 버전은 0.6.1이었습니다.
활성화 방법: 기능의 메타 데이터(meta)에 mcp.public을 true로 설정하면 기본 MCP 서버에 해당 기능이 표시됩니다. 더 광범위한 public 플래그를 사용하는 것도 가능합니다.
기본 엔드포인트: /wp-json/mcp/mcp-adapter-default-server
로그인: WordPress 사용자 및 애플리케이션 비밀번호.
먼저 로컬 사이트에서 시도해 보세요. AI 도구는 연결하는 사용자와 동일한 권한을 갖게 됩니다.

MCP란 무엇인가요? 간단히 설명하면

MCP는 AI 앱이 외부 도구 및 데이터에 연결할 수 있는 공유된 방법을 제공하는 개방형 표준입니다. MCP 서버는 자신이 제공하는 도구 목록을 나열합니다. Claude Code나 Cursor 같은 MCP 클라이언트는 이 목록을 읽고 사용자가 요청할 때 해당 도구를 호출할 수 있습니다.

WordPress는 이미 'Abilities API'라는 자체적인 동작 설명 방식을 가지고 있습니다. 저는 첫 번째 Abilities API 통합 게시물에서 이를 다루었습니다. 각 기능은 이름, 입력 스키마(input schema), 출력 스키마(output schema), 권한 확인(permission check), 그리고 콜백(callback)을 가집니다. MCP Adapter는 이러한 기능을 가져와 MCP 클라이언트가 읽을 수 있는 형태로 만듭니다.

요청이 스택을 통과하는 방식은 다음과 같습니다:

사용자가 Claude Code 또는 Cursor에 질문을 합니다.
클라이언트가 사이트에 있는 어댑터의 서버를 호출합니다.
어댑터는 일치하는 기능을 찾습니다.
코드가 실행되기 전에 WordPress가 연결된 사용자에게 해당 기능의 권한 확인을 수행합니다.
결과는 구조화된 데이터로 클라이언트로 전송됩니다.

WordPress MCP Adapter 다이어그램: 중앙에 있는 WordPress 사이트와 터미널, 코드 에디터가 연결되어 있으며, 로그인 및 권한을 위한 자물쇠, 열쇠, 방패 아이콘이 있습니다.

!WordPress MCP Adapter 다이어그램: 중앙에 있는 WordPress 사이트와 터미널, 코드 에디터가 연결되어 있으며, 로그인 및 권한을 위한 자물쇠, 열쇠, 방패 아이콘이 있습니다.

WordPress MCP Adapter는 사용자의 사이트와 Claude Code 및 Cursor 같은 AI 도구 사이에 위치합니다.

1단계: WordPress MCP Adapter 설치하기

어댑터가 아직 코어 기능에 포함되어 있지 않으므로, 직접 추가해야 합니다. 플러그인으로 설치하거나 자체 플러그인의 Composer 패키지로 번들링할 수 있습니다. 첫 테스트를 위해서는 더 간단한 플러그인 방식을 추천합니다.

Composer 방식은 어댑터에 의존하는 플러그인을 배포하게 될 때 의미가 있습니다. composer require wordpress/mcp-adapter를 실행하면 자체 코드와 함께 설치되므로, 어댑터가 플러그인과 함께 이동합니다.

플러그인 설치 방법:

WordPress/mcp-adapter 저장소에서 최신 릴리스를 다운로드합니다.
로컬 또는 스테이징 사이트에서 플러그인으로 업로드합니다.
활성화하고, 사이트가 WordPress 6.9 이상을 실행하는지 확인합니다.

참고: 어댑터는 아직 버전 1.0이므로, 이름과 명령어는 릴리스마다 변경될 수 있습니다. 아래 내용을 복사하기 전에 설치한 버전의 README를 읽어보세요.

2단계: MCP용 기능(ability)을 공개로 표시하기

어떤 기능을 등록한다고 해서 자동으로 AI 도구와 공유되는 것은 아닙니다. 기능의 meta 배열 안에 'mcp' => array( 'public' => true )를 추가하여 명시적으로 옵트인해야 합니다.

이 플래그는 해당 기능을 MCP를 통해서만 공유하며 다른 곳에서는 공유하지 않습니다. 어댑터 README에는 meta 내에서 더 광범위한 public 플래그도 설명되어 있으며, 기본 서버가 이 플래그 또한 인식합니다.

데이터만 읽어오는 간단한 예시입니다. 사이트 이름과 태그라인을 반환하며, 포스트를 편집할 수 있는 사용자에게만 실행됩니다.

add_action( 'wp_abilities_api_categories_init', function () {
    wp_register_ability_category( 'my-site', array(
        'label'       => 'My Site',
...

readonly 주석은 클라이언트에게 이 기능이 아무것도 변경하지 않음을 알려줍니다. 권한 콜백은 요청이 AI 도구에서 오는 경우에도 호출될 때마다 실행됩니다.

3단계: 기본 서버 엔드포인트 알아보기

플러그인이 활성화되면, 어댑터가 기본 MCP 서버를 설정합니다. 이 경력에서 사이트 내 경로를 찾을 수 있습니다:

이 서버는 각 공개 기능을 개별 도구로 나열하지 않습니다. 대신 세 가지 일반적인 도구를 제공합니다:

공개 기능들을 찾는 도구.
단일 기능에 대한 상세 정보를 가져오는 도구.
기능을 실행하는 도구.

README에서는 이들을 mcp-adapter/discover-abilities, mcp-adapter/get-ability-info, 그리고 mcp-adapter/execute-ability라고 부릅니다. 따라서 클라이언트는 먼저 기능을 찾고, 그 다음 호출하게 됩니다.

만약 모든 기능을 개별 도구로 나열하고 싶다면, 사용자 지정 서버를 등록할 수 있습니다. 기본 서버가 작동하는 것을 확인한 후에 시도해 보는 것이 좋습니다.

4단계: 애플리케이션 비밀번호 생성하기

애플리케이션 비밀번호는 WordPress에 내장되어 있습니다. 외부 앱이 주 비밀번호 없이 REST API를 통해 로그인할 수 있게 해주며, 각각의 비밀번호를 개별적으로 취소(revoke)할 수 있습니다.

AI 도구가 사용할 사용자의 프로필 페이지를 엽니다.
'애플리케이션 비밀번호'까지 스크롤합니다.

💡 팁: 이를 위해 별도의 사용자를 만들고 권한 확인을 통과하는 데 필요한 가장 낮은 역할을 부여하세요. 좋은 이유가 없다면 AI 도구를 관리자(admin)로 연결하지 마세요.

5단계: Cursor 및 Claude Code 연결하기

HTTP 연결의 경우, 어댑터 문서는 @automattic/mcp-wordpress-remote라는 작은 프록시 패키지를 제안합니다. 이 패키지는 컴퓨터에서 npx를 통해 실행되며 로그인 과정을 처리해 줍니다.

두 가지 연결 유형은 서로 다른 환경에 적합합니다:

STDIO: 사이트와 동일한 장치에서 WP-CLI를 통해 서버를 실행합니다. 비밀번호가 필요 없으며 로컬 개발에 적합합니다.
HTTP: 애플리케이션 비밀번호(Application Password)를 사용하여 REST API를 통해 연결합니다. 스테이징 사이트나 터미널에서 접근할 수 없는 모든 경우에 사용하세요.

Cursor

프로젝트의 .cursor/mcp.json 파일에 다음 내용을 추가한 후 Cursor를 재시작하세요:

{
  "mcpServers": {
    "wordpress-local": {
...

Claude Code

로컬 사이트에서 WP-CLI가 작동한다면, HTTP를 건너뛰고 STDIO를 사용할 수 있습니다. 이 명령어는 선택한 사용자로 WP-CLI를 통해 서버를 실행합니다:

claude mcp add wordpress-local -- wp --path=/path/to/site mcp-adapter serve --server=mcp-adapter-default-server --user=mcp-user

Claude Code에 Cursor가 사용하는 것과 동일한 npx 설정을 제공할 수도 있습니다.

연결이 완료되면, 도구에게 사이트의 사용 가능한 기능(abilities) 목록을 요청하세요. 목록에서 my-site/get-site-info를 볼 수 있어야 합니다.

다음 단계로 넘어가기 전 안전 점검 사항

읽기 전용 기능부터 시작하세요. 데이터를 가져오는(fetch) 능력만 먼저 공유하고, 생성(create), 수정(edit), 삭제(delete)와 같은 기능을 추가하는 것은 나중에 하세요.
권한 콜백을 엄격하게 유지하세요. 누구에게나 항상 true를 반환하지 마세요. 이 콜백이 사람들을 막아주는 핵심입니다.
비밀번호는 git에 넣지 마세요. 만약 .cursor/mcp.json 파일에 비밀번호가 포함되어 있다면, 이를 .gitignore에 추가하세요.
승인하기 전에 확인하세요. 두 도구 모두 도구 호출(tool call)을 실행하기 전에 사용자에게 묻습니다. '예'라고 말하기 전에 입력 내용을 읽어보세요.
실패한 권한 검사를 테스트하세요. 읽기 전용 기능이 작동하는 것을 먼저 확인하고, 그 다음으로 검사에서 '아니요'가 나올 때 어떤 일이 발생하는지 살펴보세요. 이 테스트는 성공했을 때보다 안전에 대해 더 많은 것을 가르쳐 줍니다.
작업을 완료하면 비밀번호를 취소하세요. 테스트를 중단할 때는 애플리케이션 비밀번호(Application Password)를 삭제하세요.
신뢰하기 전까지는 로컬 환경에 머무르세요. AI 도구를 첫날부터 클라이언트의 라이브 사이트에 연결하지 마세요.

FAQ

WordPress MCP 어댑터가 WordPress 코어의 일부인가요?

아닙니다. WordPress 6.9에는 Abilities API가 코어에 포함되어 있지만, MCP Adapter는 GitHub에서 설치하는 별도의 플러그인입니다. 여전히 버전 1.0이므로, 릴리스 간 변화를 예상해야 합니다.

Claude Code 연결을 위해 WP-CLI가 필요한가요?

아닙니다. WP-CLI는 로컬 사이트에서 STDIO 연결을 제공합니다. 이것 없이도 npx 프록시와 애플리케이션 비밀번호를 사용하여 HTTP 엔드포인트로 접속할 수 있으며, Cursor가 연결하는 방식과 동일합니다.

AI 도구가 MCP를 통해 제 사이트를 변경할 수 있나요?

공개(public)로 표시한 기능들을 통해서만 가능하며, 연결된 사용자가 각 기능의 권한 콜백을 통과했을 때만 가능합니다. 읽기 전용 기능부터 시작하고 낮은 역할(low role)을 가진 사용자에게 적용하세요.

제 기능이 Cursor나 Claude Code에 나타나지 않는 이유는 무엇인가요?

먼저 세 가지를 확인해 보세요:

기능의 meta에 mcp public 플래그가 필요합니다.
어댑터 플러그인이 활성화되어 있어야 합니다.
사이트가 WordPress 6.9 이상을 실행해야 합니다.

그런 다음 도구에게 기능을 다시 목록화(list)해 달라고 요청하세요.

여러분 차례입니다

저는 이 설정에 대해 아직 초기 단계이며, 여러분의 경험이 어땠는지 듣고 싶습니다.

Claude Code나 Cursor를 WordPress 사이트에 연결해 본 적이 있나요? STDIO 방식과 HTTP 방식 중 어떤 것을 사용했나요?
실제 사이트에서 가장 먼저 노출할 기능은 무엇인가요?
권한 확인(permission check) 때문에 작동할 것이라 예상했던 무언가가 막힌 적이 있나요?

댓글로 알려주세요. 문제가 발생했던 부분까지 모두 포함해서요. 모든 답글을 읽겠습니다.

계속 읽기

저는 WordPress 개발 AI 워크플로우에서 이 도구들 간의 작업 분배 방식을 설명할 예정입니다. 또한 AI가 제 WordPress 작업을 가속화하는 지점과 그렇지 않은 지점에 대해서도 작성했습니다.

원래 matthummel.com에 게시되었습니다.