Ghost MCPサーバー

これはMFYDev/ghost-mcpのフォークであり、現在は@hithereiamaliffによって保守・改善されています。

このModel Context Protocol (MCP)サーバーは、大規模言語モデル (LLM) インターフェースを使用してGhost CMSインスタンスを管理するための強力で柔軟な方法を提供します。ブログの管理機能への包括的かつ安全なアクセスを提供し、コンテンツ管理ワークフローの自動化と効率化を可能にします。

機能

堅牢なAPI統合: すべてのAdmin API操作に直接認証された axios 呼び出しを使用し、外部ライブラリに依存しない安定した信頼性の高い接続を保証します。
包括的なエンティティアクセス: 投稿、ユーザー、メンバー、ティア、オファー、ニュースレターを管理します。
強化されたエラーハンドリング: 詳細なステータスコードとレスポンスボディを提供します。
モダンなトランスポート: 非推奨となったSTDIOロジックをすべて削除し、Streamable HTTPトランスポートのみを使用します。
診断ツール: APIの接続性と設定をトラブルシューティングするためのツールが含まれています。
マルチテナントサポート: mcp-key-service を使用しているため、パブリック/共有デプロイメントで生のGhost認証情報がMCP URLに公開されることはありません。
Firebase Analytics: Firebase Realtime Databaseとローカルファイルバックアップによるクラウドベースの分析ストレージ。
VPSデプロイ対応: Docker、Nginx、GitHub Actionsによる自動デプロイをサポート。

インストールと使用方法

このMCPサーバーは、2つのデプロイ方法で利用可能です。

方法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 Cloudプラットフォーム

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

注意: 最初に mcpkeys.techmavie.digital でGhost認証情報を登録し、usr_ キーを取得してください。

設定

この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リソースが利用可能です:

Posts: Ghostサイトで公開された記事やコンテンツ。
Members: サイトの登録ユーザーおよび購読者。
Newsletters: Ghost経由で管理・送信されるメールニュースレター。
Offers: メンバー向けのプロモーションオファーや割引。
Invites: Ghostサイトに参加するための新規ユーザーやスタッフへの招待。
Roles: Ghost管理画面内のユーザーロールと権限。
Tags: 投稿やコンテンツを整理するためのタグ。
Tiers: メンバー向けのサブスクリプションティアやプラン。
Users: 管理ユーザーやスタッフアカウント。
Webhooks: 外部サービスへの自動イベント通知。

利用可能なツール

このMCPサーバーは、Ghost CMSを管理するための幅広いツールを提供します。これらのツールはModel Context Protocolを通じて公開され、ブログのリソースに対するCRUD (作成、読み取り、更新、削除) 操作を完全に行うことができます。以下は利用可能なツールセットの概要です:

Posts

Browse Posts: フィルタ、ページネーション、並べ替えを指定して投稿を一覧表示します。
Read Post: IDまたはスラッグで投稿を取得します。
Add Post: タイトル、コンテンツ、ステータスを指定して新しい投稿を作成します。
Edit Post: IDで既存の投稿を更新します。
Delete Post: IDで投稿を削除します。

Members

Browse Members: フィルタとページネーションを指定してメンバーを一覧表示します。
Read Member: IDまたはメールアドレスでメンバーを取得します。
Add Member: 新しいメンバーを作成します。
Edit Member: メンバーの詳細を更新します。
Delete Member: メンバーを削除します。

Newsletters

Browse Newsletters: ニュースレターを一覧表示します。
Read Newsletter: IDでニュースレターを取得します。
Add Newsletter: 新しいニュースレターを作成します。
Edit Newsletter: ニュースレターの詳細を更新します。
Delete Newsletter: ニュースレターを削除します。

Offers

Browse Offers: オファーを一覧表示します。
Read Offer: IDでオファーを取得します。
Add Offer: 新しいオファーを作成します。
Edit Offer: オファーの詳細を更新します。
Delete Offer: オファーを削除します。

Invites

Browse Invites: 招待を一覧表示します。
Add Invite: 新しい招待を作成します。
Delete Invite: 招待を削除します。

Roles

Browse Roles: ロールを一覧表示します。
Read Role: IDでロールを取得します。

Tiers

Browse Tiers: ティアを一覧表示します。
Read Tier: IDでティアを取得します。
Add Tier: 新しいティアを作成します。
Edit Tier: ティアの詳細を更新します。
Delete Tier: ティアを削除します。

Users

Browse Users: ユーザーを一覧表示します。
Read User: IDまたはスラッグでユーザーを取得します。
Edit User: ユーザーの詳細を更新します。
Delete User: ユーザーを削除します。

Webhooks

Browse Webhooks: Webhookを一覧表示します。
Add Webhook: 新しいWebhookを作成します。
Delete Webhook: Webhookを削除します。

各ツールは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トランスポートを実装しています。サーバーは自動的に text/event-stream をAcceptヘッダーに注入し、セッションの競合を防ぐためにリクエストごとに分離されたトランスポートインスタンスを作成します。

適切なMCP初期化によるエンドポイントのテスト:

# Test MCP initialization (proper way to test)
curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  "https://mcp.techmavie.digital/ghostcms/mcp/usr_YOUR_USER_KEY"

# Expected response (SSE format):
# event: message
# data: {"result":{"protocolVersion":"2024-11-05","capabilities":{...},"serverInfo":{...}},"jsonrpc":"2.0","id":1}

注意: 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 Analytics

このMCPサーバーは、フォールバックとしてローカルファイルバックアップを備えたクラウドベースの分析ストレージにFirebase Realtime Databaseを使用します。

機能

デュアルストレージ: Firebase (プライマリ) + ローカルファイル (バックアップ)
永続的: コンテナの再構築やデプロイ後もデータが保持されます
リアルタイム: 60秒ごとに更新
ダッシュボード: /analytics/dashboard でビジュアル分析を表示

追跡データ

リクエストとツール呼び出しの合計
メソッド別のリクエスト (GET, POSTなど)
エンドポイント別のリクエスト
ツール使用統計
クライアントIPとユーザーエージェント
時間別のリクエスト傾向
最近のツール呼び出しアクティビティ

Firebaseセットアップ

FirebaseコンソールでFirebaseプロジェクトを作成します
Realtime Databaseを有効にします
サービスアカウント認証情報を生成します (プロジェクト設定 → サービスアカウント)
認証情報を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