WordPress MCP Server

WordPress MCP Server

WordPress REST API를 MCP(Model Context Protocol)로 래핑한 Node.js 서버.AI 에이전트에서 WordPress 게시글을 조회, 생성, 수정, 삭제할 수 있다.

프로젝트 구조

├── src/
│   ├── config.ts             # 환경 변수 로드 및 설정 타입 정의
│   ├── logger.ts             # stderr 기반 로거 (STDIO 모드 안전)
│   ├── wordpress-client.ts   # WordPress REST API 클라이언트
│   ├── server.ts             # MCP 서버 생성 + Tool 등록 (공통 로직)
│   ├── stdio.ts              # STDIO 전송 방식 진입점
│   └── sse.ts                # Streamable HTTP + 레거시 SSE 전송 방식 진입점
├── dist/                     # TypeScript 빌드 출력
├── .env.example              # 환경 변수 예시
├── package.json
└── tsconfig.json

아키텍처

┌─────────────┐     ┌──────────────────────────┐
│  stdio.ts   │     │         sse.ts           │
│ (StdioTx)   │     │ (Express)                │
│             │     │  ┌─────────────────────┐ │
│             │     │  │ Streamable HTTP      │ │
│             │     │  │ POST|GET|DELETE /mcp │ │
│             │     │  ├─────────────────────┤ │
│             │     │  │ Legacy SSE          │ │
│             │     │  │ GET /sse            │ │
│             │     │  │ POST /messages      │ │
│             │     │  └─────────────────────┘ │
└──────┬──────┘     └────────────┬─────────────┘
       │                         │
       └───────────┬─────────────┘
                   │
           ┌───────▼───────┐
           │   server.ts   │
           │ (McpServer +  │
           │  Tool 정의)   │
           └───────┬───────┘
                   │
         ┌─────────▼─────────┐
         │ wordpress-client  │
         │ (REST API 호출)   │
         └─────────┬─────────┘
                   │
           ┌───────▼───────┐
           │   WordPress   │
           │  /wp-json/v2  │
           └───────────────┘

server.ts의 createServer()가 공통 로직 레이어이며, STDIO와 SSE 양쪽에서 동일하게 사용된다.

사전 요구사항

• Node.js 18+
• WordPress 사이트 (REST API 활성화 상태)
• WordPress Application Password 또는 Bearer Token

WordPress Application Password 발급

1. WordPress 관리자 > 사용자 > 프로필
2. "애플리케이션 비밀번호" 섹션에서 이름을 입력하고 생성
3. 표시되는 비밀번호를 복사 (공백 포함 그대로 사용)

설치

npm install
npm run build

환경 변수 설정

cp .env.example .env

.env 파일을 편집한다:

# WordPress 사이트 URL (trailing slash 없이)
WORDPRESS_BASE_URL=https://your-wordpress-site.com

# 인증 방식 1: Application Password (권장)
WORDPRESS_USERNAME=admin
WORDPRESS_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx

# 인증 방식 2: Bearer Token (Application Password 대신 사용)
# WORDPRESS_TOKEN=your-bearer-token

# SSE 서버 포트 (기본값: 3000)
SSE_PORT=3000

# 자체 서명 인증서 허용 (로컬 HTTPS 개발 환경에서 사용)
# WORDPRESS_TLS_REJECT_UNAUTHORIZED=false

WORDPRESS_TOKEN이 설정되면 Bearer 인증을 사용하고, 없으면 WORDPRESS_USERNAME + WORDPRESS_APP_PASSWORD로 Basic 인증을 사용한다.

실행

STDIO 모드

로컬 MCP 클라이언트(Claude Desktop, Claude Code 등)에서 사용하는 방식.

# 빌드 후 실행
npm run start:stdio

# 개발 모드 (tsx 직접 실행)
npm run dev:stdio

SSE(HTTP) 모드

원격 MCP 클라이언트에서 HTTP로 접속하는 방식. Streamable HTTP(최신)와 레거시 SSE(구버전 클라이언트 호환) 두 가지 프로토콜을 동시에 지원한다.

# 빌드 후 실행
npm run start:sse

# 개발 모드
npm run dev:sse

서버 시작 후 사용 가능한 엔드포인트:

Streamable HTTP (최신 프로토콜)

Legacy SSE (구버전 클라이언트 호환)

공통

클라이언트 설정

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "wordpress": {
      "command": "node",
      "args": ["/절대경로/wordpress-mcp-server/dist/stdio.js"],
      "env": {
        "WORDPRESS_BASE_URL": "https://your-site.com",
        "WORDPRESS_USERNAME": "admin",
        "WORDPRESS_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
      }
    }
  }
}

Claude Code

claude mcp add wordpress -- node /절대경로/wordpress-mcp-server/dist/stdio.js

또는 .mcp.json:

{
  "mcpServers": {
    "wordpress": {
      "command": "node",
      "args": ["/절대경로/wordpress-mcp-server/dist/stdio.js"],
      "env": {
        "WORDPRESS_BASE_URL": "https://your-site.com",
        "WORDPRESS_USERNAME": "admin",
        "WORDPRESS_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx",
        "WORDPRESS_TLS_REJECT_UNAUTHORIZED": "false"
      }
    }
  }
}

SSE 모드 클라이언트 연결

SSE 서버를 실행한 후, MCP 클라이언트에서 접속:

# Streamable HTTP 지원 클라이언트 (최신)
http://localhost:3000/mcp

# Legacy SSE 지원 클라이언트 (구버전)
http://localhost:3000/sse

MCP Tools

listPosts

게시글 목록을 조회한다. 페이지네이션, 검색, 상태 필터를 지원한다.

getPost

게시글 하나를 ID로 조회한다.

createPost

새 게시글을 생성한다.

updatePost

기존 게시글을 수정한다. 전달된 필드만 변경된다.

deletePost

게시글을 삭제한다.

기술 스택

주요 설계 결정

• 공통 로직 분리: server.ts의 createServer(config) 함수가 McpServer 인스턴스와 모든 Tool을 생성한다. STDIO와 SSE 진입점은 전송 방식만 다르다.
• stderr 로깅: STDIO 모드에서 stdout은 JSON-RPC 프로토콜 메시지 전용이므로, 모든 로그는 console.error(stderr)로 출력한다.
• 듀얼 전송 프로토콜: SSE 서버가 Streamable HTTP(/mcp)와 레거시 SSE(/sse + /messages)를 동시에 제공한다. 최신 클라이언트와 구버전 클라이언트 모두 호환된다.
• 세션 관리: 두 전송 방식 모두 클라이언트별 독립 세션을 생성한다. Streamable HTTP는 mcp-session-id 헤더, 레거시 SSE는 sessionId 쿼리 파라미터로 세션을 식별한다.
• 오류 처리: WordPress API 오류 응답(4xx, 5xx)을 파싱하여 MCP isError: true 결과로 반환한다. 에이전트가 오류 내용을 이해하고 대응할 수 있다.