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 자동 배포를 지원합니다.

설치 및 사용법

이 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 또는 슬러그로 사용자를 가져옵니다.
사용자 편집: 사용자 세부 정보를 업데이트합니다.
사용자 삭제: 사용자를 삭제합니다.

웹훅

웹훅 탐색: 웹훅 목록을 조회합니다.
웹훅 추가: 새 웹훅을 생성합니다.
웹훅 삭제: 웹훅을 삭제합니다.

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

오류 처리 및 진단

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

HTTP 상태 코드가 캡처되고 보고됩니다.
전체 응답 본문이 오류 메시지에 포함됩니다.
런타임 구성이 시작 시 기록됩니다.
연결 문제를 해결하기 위한 진단 도구를 사용할 수 있습니다:
- admin_site_ping: Ghost Admin API 엔드포인트에 도달할 수 있는지 테스트합니다.
- config_echo: 현재 Ghost API 구성을 표시합니다 (키는 마스킹됨).

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

잘못된 API URL 형식
누락되거나 잘못된 형식의 Admin API 키
API 버전 불일치
네트워크/프록시 구성 문제

개발

설정

저장소 복제
종속성 설치: npm install

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

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

프로젝트 빌드: npm run build
개발 서버 시작: npm run dev

문제 해결

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

Ghost Admin API 키가 올바른 id:secret 형식인지 확인하세요.
GHOST_API_URL이 Ghost 인스턴스의 올바른 도메인인지 확인하세요.
admin_site_ping 도구를 사용하여 Admin API 엔드포인트에 도달할 수 있는지 확인하세요.
서버 로그에서 실제로 사용 중인 구성을 확인하세요.

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를 얻습니다.
여러 클라이언트가 세션 충돌 없이 동시에 연결할 수 있습니다.
세션은 응답이 전송된 후 자동으로 정리됩니다.

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

오류	원인	해결 방법
`"Not Acceptable: Client must accept text/event-stream"`	이전 서버 버전	최신 버전으로 업데이트 - 수정됨
`"Bad Request: Server not initialized"`	MCP 프로토콜 없이 테스트	적절한 MCP 초기화 사용 (위 예시 참조)
`"Mcp-Session-Id header is required"`	세션 충돌이 있는 이전 서버 버전	최신 버전으로 업데이트 - 수정됨
`"Server already initialized"`	전송을 재사용하는 이전 서버 버전	최신 버전으로 업데이트 - 수정됨

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

엔드포인트

엔드포인트	설명
`/health`	상태 확인
`/mcp/:userKey`	MCP 엔드포인트 (호스팅된 키 서비스)
`/analytics`	분석 JSON 데이터
`/analytics/dashboard`	시각적 분석 대시보드
`/analytics/tools`	도구 사용 통계

Firebase 분석

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

주요 기능

이중 저장소: Firebase (기본) + 로컬 파일 (백업)
지속성: 컨테이너 재빌드 및 배포 후에도 데이터 유지
실시간: 60초마다 업데이트
대시보드: /analytics/dashboard에서 시각적 분석 제공

추적 데이터

총 요청 및 도구 호출 수
메서드별 요청 (GET, POST 등)
엔드포인트별 요청
도구 사용 통계
클라이언트 IP 및 사용자 에이전트
시간별 요청 추세
최근 도구 호출 활동

Firebase 설정

Firebase 콘솔에서 Firebase 프로젝트 생성
실시간 데이터베이스 활성화
서비스 계정 자격 증명 생성 (프로젝트 설정 → 서비스 계정)
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를 참조하세요.

기여

저장소 포크
기능 브랜치 생성
변경 사항 커밋
풀 리퀘스트 생성

라이선스

MIT

Ghost MCP 서버

주요 기능

설치 및 사용법

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

Claude Desktop과 함께 사용하기

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

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

MCP URL 형식

Claude Desktop 사용 예시

라이브 데모

구성

사용 가능한 리소스

사용 가능한 도구

게시물

멤버

뉴스레터

오퍼

초대

역할

태그

티어

사용자

웹훅

오류 처리 및 진단

개발

설정

문제 해결

MCP Streamable HTTP 요구 사항

VPS 배포

아키텍처

배포 파일

빠른 배포

엔드포인트

Firebase 분석

주요 기능

추적 데이터

Firebase 설정

Firebase 데이터 구조

기여

라이선스

Resources

Latest Blog Posts

MCP directory API