Ghost MCP-Server

Dies ist ein Fork von MFYDev/ghost-mcp, der nun von @hithereiamaliff gewartet und verbessert wird.

Dieser Model Context Protocol (MCP)-Server bietet eine leistungsstarke und flexible Möglichkeit, Ihre Ghost CMS-Instanz über Schnittstellen für große Sprachmodelle (LLMs) zu verwalten. Er bietet umfassenden und sicheren Zugriff auf die administrativen Funktionen Ihres Blogs, sodass Sie Ihre Content-Management-Workflows automatisieren und optimieren können.

Funktionen

• Robuste API-Integration: Nutzt direkte, authentifizierte axios-Aufrufe für alle Admin-API-Operationen, was eine stabile und zuverlässige Verbindung gewährleistet, die nicht von externen Bibliotheken abhängig ist.

• Umfassender Entitätszugriff: Verwaltet Beiträge, Benutzer, Mitglieder, Tarife, Angebote und Newsletter.

• Erweiterte Fehlerbehandlung: Bietet detaillierte Statuscodes und Antworttexte.

• Moderner Transport: Verwendet ausschließlich den Streamable HTTP-Transport; die gesamte veraltete STDIO-Logik wurde entfernt.

• Diagnosetools: Enthält Tools zur Fehlerbehebung bei API-Konnektivität und Konfiguration.

• Multi-Tenant-Unterstützung: Verwendet mcp-key-service, sodass öffentliche/geteilte Bereitstellungen niemals rohe Ghost-Anmeldedaten in MCP-URLs offenlegen.

• Firebase-Analyse: Cloud-basierte Analysedatenspeicherung mit Firebase Realtime Database und lokaler Dateisicherung.

• Bereit für VPS-Deployment: Unterstützung für Docker, Nginx und GitHub Actions Auto-Deployment.

Installation & Verwendung

Dieser MCP-Server ist über zwei Bereitstellungsmethoden verfügbar:

Methode 1: NPM-Paket (Empfohlen für MCP-Clients)

Direkt von npm installieren:

npm install -g mcp-ghostcms

Oder mit npx verwenden (keine Installation erforderlich):

npx mcp-ghostcms

Verwendung mit Claude Desktop

Um den Server mit MCP-Clients wie Claude Desktop zu verwenden, fügen Sie Folgendes zu Ihrer claude_desktop_config.json hinzu:

{
  "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"
        }
      }
    }
}

Methode 2: Smithery Cloud-Plattform

Bereitstellen und Ausführen auf der Cloud-Plattform von Smithery:

Oder für die lokale Entwicklung mit Smithery:

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

Dies startet den Server auf Port 8080 und öffnet das Smithery Playground in Ihrem Browser.

Methode 3: Selbstgehosteter VPS mit MCP Key Service

Für öffentliche/geteilte Bereitstellungen kann dieser MCP-Server auf einem VPS selbst gehostet werden und löst Ghost-Anmeldedaten über mcp-key-service auf. Benutzer registrieren ihre Ghost-Site-URL und ihren Admin-Schlüssel einmal, erhalten einen usr_XXXXXXXX-Schlüssel, und nur dieser Benutzerschlüssel erscheint in der MCP-URL.

MCP-URL-Format

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

Alternative Form mit Abfrageparametern:

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

Beispiel für die Verwendung mit Claude Desktop

Fügen Sie dies zu Ihrer claude_desktop_config.json hinzu:

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

Live-Demo

Eine öffentliche Instanz ist verfügbar unter:

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

Hinweis: Registrieren Sie Ihre Ghost-Anmeldedaten unter mcpkeys.techmavie.digital, um zuerst einen usr_-Schlüssel zu erhalten.

Konfiguration

Dieser MCP-Server erfordert die folgende Konfiguration:

• GHOST_API_URL: Ihre Ghost-Site-URL (nur Domain, kein Pfad), z. B. https://yourghostbloginstance.com

• GHOST_ADMIN_API_KEY: Ihr Ghost Admin API-Schlüssel im Format id:secret (aus Ghost Admin → Einstellungen → Integrationen).

• GHOST_API_VERSION: Ghost-API-Version (v5.0 für Ghost 5.x, v6.0 für Ghost 6.x).

• GHOST_CONTENT_API_KEY (optional): Ihr Ghost Content API-Schlüssel für schreibgeschützte Operationen.

Für den gehosteten HTTP-Modus konfigurieren Sie KEY_SERVICE_URL und KEY_SERVICE_TOKEN auf dem Server und setzen Sie MCP_API_KEY, wenn Sie die Analyse-Endpunkte mit einem X-API-Key-Header schützen möchten.

Verfügbare Ressourcen

Die folgenden Ghost CMS-Ressourcen sind über diesen MCP-Server verfügbar:

• Beiträge: Artikel und Inhalte, die auf Ihrer Ghost-Site veröffentlicht wurden.

• Mitglieder: Registrierte Benutzer und Abonnenten Ihrer Site.

• Newsletter: E-Mail-Newsletter, die über Ghost verwaltet und versendet werden.

• Angebote: Werbeaktionen und Rabatte für Mitglieder.

• Einladungen: Einladungen für neue Benutzer oder Mitarbeiter, Ihrer Ghost-Site beizutreten.

• Rollen: Benutzerrollen und Berechtigungen innerhalb des Ghost-Admins.

• Tags: Organisatorische Tags für Beiträge und Inhalte.

• Tarife: Abonnement-Tarife und Pläne für Mitglieder.

• Benutzer: Admin-Benutzer und Mitarbeiterkonten.

• Webhooks: Automatisierte Ereignisbenachrichtigungen an externe Dienste.

Verfügbare Tools

Dieser MCP-Server bietet eine breite Palette an Tools zur Verwaltung Ihres Ghost CMS. Diese Tools werden über das Model Context Protocol bereitgestellt und ermöglichen eine vollständige Palette von CRUD-Operationen (Erstellen, Lesen, Aktualisieren, Löschen) für die Ressourcen Ihres Blogs. Nachfolgend finden Sie einen Überblick über das verfügbare Toolset:

Beiträge

• Beiträge durchsuchen: Beiträge mit optionalen Filtern, Paginierung und Sortierung auflisten.

• Beitrag lesen: Einen Beitrag nach ID oder Slug abrufen.

• Beitrag hinzufügen: Einen neuen Beitrag mit Titel, Inhalt und Status erstellen.

• Beitrag bearbeiten: Einen bestehenden Beitrag nach ID aktualisieren.

• Beitrag löschen: Einen Beitrag nach ID entfernen.

Mitglieder

• Mitglieder durchsuchen: Mitglieder mit Filtern und Paginierung auflisten.

• Mitglied lesen: Ein Mitglied nach ID oder E-Mail abrufen.

• Mitglied hinzufügen: Ein neues Mitglied erstellen.

• Mitglied bearbeiten: Mitgliedsdetails aktualisieren.

• Mitglied löschen: Ein Mitglied entfernen.

Newsletter

• Newsletter durchsuchen: Newsletter auflisten.

• Newsletter lesen: Einen Newsletter nach ID abrufen.

• Newsletter hinzufügen: Einen neuen Newsletter erstellen.

• Newsletter bearbeiten: Newsletter-Details aktualisieren.

• Newsletter löschen: Einen Newsletter entfernen.

Angebote

• Angebote durchsuchen: Angebote auflisten.

• Angebot lesen: Ein Angebot nach ID abrufen.

• Angebot hinzufügen: Ein neues Angebot erstellen.

• Angebot bearbeiten: Angebotsdetails aktualisieren.

• Angebot löschen: Ein Angebot entfernen.

Einladungen

• Einladungen durchsuchen: Einladungen auflisten.

• Einladung hinzufügen: Eine neue Einladung erstellen.

• Einladung löschen: Eine Einladung entfernen.

Rollen

• Rollen durchsuchen: Rollen auflisten.

• Rolle lesen: Eine Rolle nach ID abrufen.

Tags

• Tags durchsuchen: Tags auflisten.

• Tag lesen: Ein Tag nach ID oder Slug abrufen.

• Tag hinzufügen: Ein neues Tag erstellen.

• Tag bearbeiten: Tag-Details aktualisieren.

• Tag löschen: Ein Tag entfernen.

Tarife

• Tarife durchsuchen: Tarife auflisten.

• Tarif lesen: Einen Tarif nach ID abrufen.

• Tarif hinzufügen: Einen neuen Tarif erstellen.

• Tarif bearbeiten: Tarifdetails aktualisieren.

• Tarif löschen: Einen Tarif entfernen.

Benutzer

• Benutzer durchsuchen: Benutzer auflisten.

• Benutzer lesen: Einen Benutzer nach ID oder Slug abrufen.

• Benutzer bearbeiten: Benutzerdetails aktualisieren.

• Benutzer löschen: Einen Benutzer entfernen.

Webhooks

• Webhooks durchsuchen: Webhooks auflisten.

• Webhook hinzufügen: Einen neuen Webhook erstellen.

• Webhook löschen: Einen Webhook entfernen.

Jedes Tool ist über das MCP-Protokoll zugänglich und kann von kompatiblen Clients aufgerufen werden. Detaillierte Parameterschemata und Verwendungshinweise finden Sie im Quellcode unter src/tools/.

Fehlerbehandlung & Diagnose

Dieser Fork enthält eine verbesserte Fehlerbehandlung, die detaillierte Informationen zu API-Fehlern liefert:

• HTTP-Statuscodes werden erfasst und gemeldet

• Vollständige Antworttexte sind in Fehlermeldungen enthalten

• Die Laufzeitkonfiguration wird beim Start protokolliert

• Diagnosetools stehen zur Fehlerbehebung bei Konnektivitätsproblemen zur Verfügung:

  • admin_site_ping: Testet, ob der Ghost Admin API-Endpunkt erreichbar ist

  • config_echo: Zeigt die aktuelle Ghost-API-Konfiguration (mit maskiertem Schlüssel)

Diese Verbesserungen erleichtern die Diagnose häufiger Probleme wie:

• Falsches API-URL-Format

• Fehlende oder falsch formatierte Admin-API-Schlüssel

• Nicht übereinstimmende API-Versionen

• Netzwerk-/Proxy-Konfigurationsprobleme

Entwicklung

Einrichtung

1. Repository klonen

2. Abhängigkeiten installieren: npm install

3. Eine .env-Datei mit Ihrer Ghost-Konfiguration erstellen:

GXP9 4. Projekt bauen: npm run build 5. Dev-Server starten: npm run dev

Fehlerbehebung

Wenn Sie auf Authentifizierungsfehler oder "Ressource nicht gefunden"-Fehler stoßen:

1. Überprüfen Sie, ob Ihr Ghost Admin API-Schlüssel das korrekte id:secret-Format hat.

2. Stellen Sie sicher, dass Ihre GHOST_API_URL die korrekte Domain für Ihre Ghost-Instanz ist.

3. Verwenden Sie das Tool admin_site_ping, um zu überprüfen, ob der Admin-API-Endpunkt erreichbar ist.

4. Überprüfen Sie die Serverprotokolle auf die tatsächlich verwendete Konfiguration.

MCP Streamable HTTP-Anforderungen

Dieser Server implementiert den MCP Streamable HTTP-Transport mit ordnungsgemäßer Sitzungsverwaltung und Accept-Header-Verarbeitung. Der Server fügt automatisch text/event-stream in die Accept-Header ein und erstellt isolierte Transportinstanzen pro Anfrage, um Sitzungskonflikte zu vermeiden.

Testen des Endpunkts mit ordnungsgemäßer MCP-Initialisierung:

# 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}

Hinweis: Einfache GET/POST-Anfragen ohne MCP-Initialisierung geben Protokollfehler wie "Bad Request: Server not initialized" zurück – dies ist das erwartete Verhalten. Der Endpunkt erfordert einen ordnungsgemäßen MCP-Protokoll-Handshake.

Für MCP-Clients (Claude Desktop, Claude iOS, Claude Code):

• MCP-Clients handhaben das Initialisierungsprotokoll und die Sitzungsverwaltung automatisch

• Stellen Sie sicher, dass Ihre MCP-URL in Ihrer Client-Konfiguration korrekt formatiert ist

• Verwenden Sie für Claude iOS die Connectors-Funktion mit der vollständigen MCP-URL unter Verwendung Ihres usr_-Schlüssels

• Fügen Sie für Claude Code den Server mit dem Typ streamable-http zu Ihren MCP-Einstellungen hinzu

Sitzungsverwaltung:

• Der Server erstellt für jede HTTP-Anfrage eine neue Transportinstanz (zustandsloses Muster)

• Jede Client-Verbindung erhält automatisch eine eindeutige Sitzungs-ID

• Mehrere Clients können gleichzeitig ohne Sitzungskonflikte eine Verbindung herstellen

• Sitzungen werden nach dem Senden der Antworten automatisch bereinigt

Häufige Fehler und Lösungen:

VPS-Bereitstellung

Dieser MCP-Server bietet volle Unterstützung für die Bereitstellung auf einem selbstgehosteten VPS mit Docker, Nginx und GitHub Actions Auto-Deployment.

Architektur

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

Bereitstellungsdateien

Das Repository enthält:

• Dockerfile - Container-Konfiguration mit Node.js 20-alpine

• docker-compose.yml - Docker-Orchestrierung mit Volumes für Analysen und Firebase-Anmeldedaten

• deploy/nginx-mcp.conf - Nginx-Reverse-Proxy-Konfiguration

• .github/workflows/deploy-vps.yml - GitHub Actions Auto-Deployment-Workflow

Schnelle Bereitstellung

# 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

Endpunkte

Firebase-Analyse

Dieser MCP-Server verwendet Firebase Realtime Database für die cloudbasierte Analysedatenspeicherung mit lokaler Dateisicherung als Fallback.

Funktionen

• Dualer Speicher: Firebase (primär) + lokale Datei (Backup)

• Persistent: Daten überstehen Container-Neuerstellungen und Bereitstellungen

• Echtzeit: Aktualisierungen alle 60 Sekunden

• Dashboard: Visuelle Analysen unter /analytics/dashboard

Verfolgte Daten

• Gesamtzahl der Anfragen und Tool-Aufrufe

• Anfragen nach Methode (GET, POST, etc.)

• Anfragen nach Endpunkt

• Tool-Nutzungsstatistiken

• Client-IPs und User-Agents

• Stündliche Anfragetrends

• Letzte Tool-Aufruf-Aktivität

Firebase-Einrichtung

1. Erstellen Sie ein Firebase-Projekt in der Firebase Console

2. Aktivieren Sie Realtime Database

3. Generieren Sie Anmeldedaten für das Dienstkonto (Projekteinstellungen → Dienstkonten)

4. Kopieren Sie die Anmeldedaten auf Ihren 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-Datenstruktur

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

Detaillierte Anweisungen zur Firebase-Einrichtung finden Sie unter FIREBASE_SETUP.md.

Mitwirken

1. Repository forken