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による自動デプロイをサポート。

Related MCP server: Ghost MCP

インストールと使用方法

この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でロールを取得します。

Tags

• Browse Tags: タグを一覧表示します。

• Read Tag: IDまたはスラッグでタグを取得します。

• Add Tag: 新しいタグを作成します。

• Edit Tag: タグの詳細を更新します。

• Delete Tag: タグを削除します。

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バージョンの不一致

• ネットワーク/プロキシ設定の問題

開発

セットアップ

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トランスポートを実装しています。サーバーは自動的に 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を取得します

• 複数のクライアントがセッションの競合なしに同時に接続できます

• セッションはレスポンス送信後に自動的にクリーンアップされます

一般的なエラーと解決策:

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 Analytics

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

機能

• デュアルストレージ: Firebase (プライマリ) + ローカルファイル (バックアップ)

• 永続的: コンテナの再構築やデプロイ後もデータが保持されます

• リアルタイム: 60秒ごとに更新

• ダッシュボード: /analytics/dashboard でビジュアル分析を表示

追跡データ

• リクエストとツール呼び出しの合計

• メソッド別のリクエスト (GET, POSTなど)

• エンドポイント別のリクエスト

• ツール使用統計

• クライアントIPとユーザーエージェント

• 時間別のリクエスト傾向

• 最近のツール呼び出しアクティビティ

Firebaseセットアップ

1. Firebaseコンソール でFirebaseプロジェクトを作成します

2. Realtime Databaseを有効にします

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