Ghost MCP 서버

이 프로젝트는 MFYDev/ghost-mcp의 포크 버전이며, 현재 @hithereiamaliff에 의해 유지 관리 및 개선되고 있습니다.

이 MCP(Model Context Protocol) 서버는 대규모 언어 모델(LLM) 인터페이스를 사용하여 Ghost CMS 인스턴스를 관리할 수 있는 강력하고 유연한 방법을 제공합니다. 블로그의 관리 기능에 대한 포괄적이고 안전한 액세스를 제공하여 콘텐츠 관리 워크플로우를 자동화하고 간소화할 수 있습니다.

주요 기능

• 강력한 API 통합: 모든 Admin API 작업에 인증된 axios 호출을 직접 사용하여 외부 라이브러리에 의존하지 않는 안정적이고 신뢰할 수 있는 연결을 보장합니다.

• 포괄적인 엔티티 액세스: 게시물, 사용자, 멤버, 티어, 오퍼 및 뉴스레터를 관리합니다.

• 향상된 오류 처리: 상세한 상태 코드와 응답 본문을 제공합니다.

• 최신 전송 방식: 더 이상 사용되지 않는 STDIO 로직을 제거하고 Streamable HTTP 전송만 독점적으로 사용합니다.

• 진단 도구: API 연결 및 구성을 문제 해결하기 위한 도구를 포함합니다.

• 멀티 테넌트 지원: mcp-key-service를 사용하여 공개/공유 배포 시 MCP URL에 원시 Ghost 자격 증명이 노출되지 않도록 합니다.

• Firebase 분석: Firebase 실시간 데이터베이스를 사용한 클라우드 기반 분석 저장소 및 로컬 파일 백업을 지원합니다.

• VPS 배포 준비 완료: Docker, Nginx 및 GitHub Actions 자동 배포를 지원합니다.

Related MCP server: Ghost MCP

설치 및 사용법

이 MCP 서버는 두 가지 배포 방법을 통해 사용할 수 있습니다:

방법 1: NPM 패키지 (MCP 클라이언트 권장)

npm에서 직접 설치:

npm install -g mcp-ghostcms

또는 npx 사용 (설치 불필요):

npx mcp-ghostcms

Claude Desktop과 함께 사용하기

Claude Desktop과 같은 MCP 클라이언트에서 사용하려면 claude_desktop_config.json에 다음을 추가하세요:

{
  "mcpServers": {
      "mcp-ghostcms": {
        "command": "npx",
        "args": ["-y", "mcp-ghostcms"],
        "env": {
            "GHOST_API_URL": "https://yourghostbloginstance.com",
            "GHOST_ADMIN_API_KEY": "your_admin_api_key",
            "GHOST_API_VERSION": "v6.0"
        }
      }
    }
}

방법 2: Smithery 클라우드 플랫폼

Smithery의 클라우드 플랫폼에 배포 및 실행:

또는 Smithery를 사용한 로컬 개발:

git clone <this-repo>
cd ghost-mcp
npm install
npm run dev

이 명령은 8080 포트에서 서버를 시작하고 브라우저에서 Smithery Playground를 엽니다.

방법 3: MCP Key Service를 사용하는 자체 호스팅 VPS

공개/공유 배포의 경우, 이 MCP 서버를 VPS에 자체 호스팅하고 mcp-key-service를 통해 Ghost 자격 증명을 해결할 수 있습니다. 사용자는 Ghost 사이트 URL과 관리자 키를 한 번 등록하여 usr_XXXXXXXX 키를 받으며, MCP URL에는 해당 사용자 키만 표시됩니다.

MCP URL 형식

https://your-domain.com/ghostcms/mcp/usr_YOUR_USER_KEY

대체 쿼리 매개변수 형식:

https://your-domain.com/ghostcms/mcp?api_key=usr_YOUR_USER_KEY

Claude Desktop 사용 예시

claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "ghost-myblog": {
      "type": "streamable-http",
      "url": "https://mcp.yourdomain.com/ghostcms/mcp/usr_YOUR_USER_KEY"
    }
  }
}

라이브 데모

공개 인스턴스는 다음에서 확인할 수 있습니다:

https://mcp.techmavie.digital/ghostcms/mcp/usr_YOUR_USER_KEY

참고: usr_ 키를 얻으려면 먼저 mcpkeys.techmavie.digital에 Ghost 자격 증명을 등록하세요.

구성

이 MCP 서버는 다음 구성이 필요합니다:

• GHOST_API_URL: Ghost 사이트 URL (도메인만, 경로 제외), 예: https://yourghostbloginstance.com

• GHOST_ADMIN_API_KEY: id:secret 형식의 Ghost Admin API 키 (Ghost 관리자 → 설정 → 통합에서 확인).

• GHOST_API_VERSION: Ghost API 버전 (Ghost 5.x의 경우 v5.0, Ghost 6.x의 경우 v6.0).

• GHOST_CONTENT_API_KEY (선택 사항): 읽기 전용 작업을 위한 Ghost Content API 키.

호스팅된 HTTP 모드의 경우 서버에서 KEY_SERVICE_URL 및 KEY_SERVICE_TOKEN을 구성하고, X-API-Key 헤더로 분석 엔드포인트를 보호하려면 MCP_API_KEY를 설정하세요.

사용 가능한 리소스

이 MCP 서버를 통해 다음 Ghost CMS 리소스를 사용할 수 있습니다:

• 게시물: Ghost 사이트에 게시된 기사 및 콘텐츠.

• 멤버: 사이트에 등록된 사용자 및 구독자.

• 뉴스레터: Ghost를 통해 관리 및 발송되는 이메일 뉴스레터.

• 오퍼: 멤버를 위한 프로모션 오퍼 및 할인.

• 초대: Ghost 사이트에 참여할 새 사용자 또는 스태프를 위한 초대.

• 역할: Ghost 관리자 내의 사용자 역할 및 권한.

• 태그: 게시물 및 콘텐츠를 위한 조직적 태그.

• 티어: 멤버를 위한 구독 티어 및 플랜.

• 사용자: 관리자 및 스태프 계정.

• 웹훅: 외부 서비스에 대한 자동화된 이벤트 알림.

사용 가능한 도구

이 MCP 서버는 Ghost CMS를 관리하기 위한 다양한 도구를 제공합니다. 이러한 도구는 Model Context Protocol을 통해 노출되며 블로그 리소스에 대한 전체 CRUD(생성, 읽기, 업데이트, 삭제) 작업을 수행할 수 있습니다. 사용 가능한 도구 세트의 개요는 다음과 같습니다:

게시물

• 게시물 탐색: 필터, 페이지 매김 및 정렬 옵션을 사용하여 게시물 목록을 조회합니다.

• 게시물 읽기: ID 또는 슬러그로 게시물을 가져옵니다.

• 게시물 추가: 제목, 콘텐츠 및 상태를 포함하여 새 게시물을 생성합니다.

• 게시물 편집: ID로 기존 게시물을 업데이트합니다.

• 게시물 삭제: ID로 게시물을 삭제합니다.

멤버

• 멤버 탐색: 필터 및 페이지 매김을 사용하여 멤버 목록을 조회합니다.

• 멤버 읽기: ID 또는 이메일로 멤버를 가져옵니다.

• 멤버 추가: 새 멤버를 생성합니다.

• 멤버 편집: 멤버 세부 정보를 업데이트합니다.

• 멤버 삭제: 멤버를 삭제합니다.

뉴스레터

• 뉴스레터 탐색: 뉴스레터 목록을 조회합니다.

• 뉴스레터 읽기: ID로 뉴스레터를 가져옵니다.

• 뉴스레터 추가: 새 뉴스레터를 생성합니다.

• 뉴스레터 편집: 뉴스레터 세부 정보를 업데이트합니다.

• 뉴스레터 삭제: 뉴스레터를 삭제합니다.

오퍼

• 오퍼 탐색: 오퍼 목록을 조회합니다.

• 오퍼 읽기: ID로 오퍼를 가져옵니다.

• 오퍼 추가: 새 오퍼를 생성합니다.

• 오퍼 편집: 오퍼 세부 정보를 업데이트합니다.

• 오퍼 삭제: 오퍼를 삭제합니다.

초대

• 초대 탐색: 초대 목록을 조회합니다.

• 초대 추가: 새 초대를 생성합니다.

• 초대 삭제: 초대를 삭제합니다.

역할

• 역할 탐색: 역할 목록을 조회합니다.

• 역할 읽기: ID로 역할을 가져옵니다.

태그

• 태그 탐색: 태그 목록을 조회합니다.

• 태그 읽기: ID 또는 슬러그로 태그를 가져옵니다.

• 태그 추가: 새 태그를 생성합니다.

• 태그 편집: 태그 세부 정보를 업데이트합니다.

• 태그 삭제: 태그를 삭제합니다.

티어

• 티어 탐색: 티어 목록을 조회합니다.

• 티어 읽기: ID로 티어를 가져옵니다.

• 티어 추가: 새 티어를 생성합니다.

• 티어 편집: 티어 세부 정보를 업데이트합니다.

• 티어 삭제: 티어를 삭제합니다.

사용자

• 사용자 탐색: 사용자 목록을 조회합니다.

• 사용자 읽기: ID 또는 슬러그로 사용자를 가져옵니다.

• 사용자 편집: 사용자 세부 정보를 업데이트합니다.

• 사용자 삭제: 사용자를 삭제합니다.

웹훅

• 웹훅 탐색: 웹훅 목록을 조회합니다.

• 웹훅 추가: 새 웹훅을 생성합니다.

• 웹훅 삭제: 웹훅을 삭제합니다.

각 도구는 MCP 프로토콜을 통해 액세스할 수 있으며 호환되는 클라이언트에서 호출할 수 있습니다. 자세한 매개변수 스키마 및 사용법은 src/tools/의 소스 코드를 참조하세요.

오류 처리 및 진단

이 포크 버전에는 API 실패에 대한 상세 정보를 제공하는 향상된 오류 처리가 포함되어 있습니다:

• HTTP 상태 코드가 캡처되고 보고됩니다.

• 전체 응답 본문이 오류 메시지에 포함됩니다.

• 런타임 구성이 시작 시 기록됩니다.

• 연결 문제를 해결하기 위한 진단 도구를 사용할 수 있습니다:

  • admin_site_ping: Ghost Admin API 엔드포인트에 도달할 수 있는지 테스트합니다.

  • config_echo: 현재 Ghost API 구성을 표시합니다 (키는 마스킹됨).

이러한 개선 사항을 통해 다음과 같은 일반적인 문제를 훨씬 쉽게 진단할 수 있습니다:

• 잘못된 API URL 형식

• 누락되거나 잘못된 형식의 Admin API 키

• API 버전 불일치

• 네트워크/프록시 구성 문제

개발

설정

1. 저장소 복제

2. 종속성 설치: npm install

3. Ghost 구성을 포함한 .env 파일 생성:

   GHOST_API_URL=https://yourghostbloginstance.com
   GHOST_ADMIN_API_KEY=your_admin_api_key
   GHOST_API_VERSION=v6.0

4. 프로젝트 빌드: npm run build

5. 개발 서버 시작: npm run dev

문제 해결

인증 또는 "Resource not found" 오류가 발생하는 경우:

1. Ghost Admin API 키가 올바른 id:secret 형식인지 확인하세요.

2. GHOST_API_URL이 Ghost 인스턴스의 올바른 도메인인지 확인하세요.

3. admin_site_ping 도구를 사용하여 Admin API 엔드포인트에 도달할 수 있는지 확인하세요.

4. 서버 로그에서 실제로 사용 중인 구성을 확인하세요.

MCP Streamable HTTP 요구 사항

이 서버는 적절한 세션 관리 및 Accept 헤더 처리를 갖춘 MCP Streamable HTTP 전송을 구현합니다. 서버는 자동으로 Accept 헤더에 text/event-stream을 삽입하고 세션 충돌을 방지하기 위해 요청당 격리된 전송 인스턴스를 생성합니다.

적절한 MCP 초기화로 엔드포인트 테스트:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Claude/MCP     │────▶│  Nginx Proxy    │────▶│  Docker         │
│  Client         │     │  /ghostcms/     │     │  Container      │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                        ▼
                                                ┌─────────────────┐
                                                │  Ghost CMS      │
                                                │  Admin API      │
                                                └─────────────────┘

참고: MCP 초기화가 없는 단순 GET/POST 요청은 "Bad Request: Server not initialized"와 같은 프로토콜 오류를 반환합니다. 이는 예상된 동작입니다. 엔드포인트는 적절한 MCP 프로토콜 핸드셰이크가 필요합니다.

MCP 클라이언트용 (Claude Desktop, Claude iOS, Claude Code):

• MCP 클라이언트는 초기화 프로토콜 및 세션 관리를 자동으로 처리합니다.

• 클라이언트 구성에서 MCP URL이 올바르게 형식화되었는지 확인하세요.

• Claude iOS의 경우 usr_ 키를 사용하여 전체 MCP URL로 커넥터 기능을 사용하세요.

• Claude Code의 경우 streamable-http 유형으로 MCP 설정에 서버를 추가하세요.

세션 관리:

• 서버는 각 HTTP 요청에 대해 새로운 전송 인스턴스를 생성합니다 (상태 비저장 패턴).

• 각 클라이언트 연결은 자동으로 고유한 세션 ID를 얻습니다.

• 여러 클라이언트가 세션 충돌 없이 동시에 연결할 수 있습니다.

• 세션은 응답이 전송된 후 자동으로 정리됩니다.

일반적인 오류 및 해결 방법:

VPS 배포

이 MCP 서버는 Docker, Nginx 및 GitHub Actions 자동 배포를 통한 자체 호스팅 VPS 배포를 완벽하게 지원합니다.

아키텍처

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Claude/MCP     │────▶│  Nginx Proxy    │────▶│  Docker         │
│  Client         │     │  /ghostcms/     │     │  Container      │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                        ▼
                                                ┌─────────────────┐
                                                │  Ghost CMS      │
                                                │  Admin API      │
                                                └─────────────────┘

배포 파일

저장소에는 다음이 포함되어 있습니다:

• Dockerfile - Node.js 20-alpine을 사용한 컨테이너 구성

• docker-compose.yml - 분석 및 Firebase 자격 증명을 위한 볼륨이 포함된 Docker 오케스트레이션

• deploy/nginx-mcp.conf - Nginx 리버스 프록시 구성

• .github/workflows/deploy-vps.yml - GitHub Actions 자동 배포 워크플로우

빠른 배포

# On your VPS
cd /opt/mcp-servers
git clone https://github.com/hithereiamaliff/mcp-ghostcms.git ghostcms
cd ghostcms

# Build and start
docker compose up -d --build

# Check logs
docker compose logs -f

엔드포인트

Firebase 분석

이 MCP 서버는 클라우드 기반 분석 저장을 위해 Firebase 실시간 데이터베이스를 사용하며, 로컬 파일 백업을 대체 수단으로 사용합니다.

주요 기능

• 이중 저장소: Firebase (기본) + 로컬 파일 (백업)

• 지속성: 컨테이너 재빌드 및 배포 후에도 데이터 유지

• 실시간: 60초마다 업데이트

• 대시보드: /analytics/dashboard에서 시각적 분석 제공

추적 데이터

• 총 요청 및 도구 호출 수

• 메서드별 요청 (GET, POST 등)

• 엔드포인트별 요청

• 도구 사용 통계

• 클라이언트 IP 및 사용자 에이전트

• 시간별 요청 추세

• 최근 도구 호출 활동

Firebase 설정

1. Firebase 콘솔에서 Firebase 프로젝트 생성

2. 실시간 데이터베이스 활성화

3. 서비스 계정 자격 증명 생성 (프로젝트 설정 → 서비스 계정)

4. VPS에 자격 증명 복사:

# On VPS
mkdir -p /opt/mcp-servers/ghostcms/.credentials
# Copy firebase-service-account.json to this directory

# Create Docker volume
docker volume create ghostcms_firebase-credentials

# Copy to volume with correct permissions
docker run --rm \
  -v ghostcms_firebase-credentials:/credentials \
  -v /opt/mcp-servers/ghostcms/.credentials:/source:ro \
  alpine sh -c "cp /source/firebase-service-account.json /credentials/ && chown -R 1001:1001 /credentials/"

# Restart container
docker compose down
docker compose up -d

Firebase 데이터 구조

mcp-analytics/
  └── mcp-ghostcms/
      ├── serverStartTime
      ├── totalRequests
      ├── totalToolCalls
      ├── requestsByMethod
      ├── requestsByEndpoint
      ├── toolCalls
      ├── recentToolCalls
      ├── clientsByIp
      ├── clientsByUserAgent
      ├── hourlyRequests
      └── lastUpdated

자세한 Firebase 설정 지침은 FIREBASE_SETUP.md를 참조하세요.

기여

1. 저장소 포크

2. 기능 브랜치 생성

3. 변경 사항 커밋

4. 풀 리퀘스트 생성

라이선스

MIT