gramps-web-mcp

Begleitender MCP-Server für die quelloffene Genealogie-Plattform Gramps Web. Er ermöglicht KI-Agenten einen strukturierten, werkzeugbasierten Zugriff auf Stammbäume über das Model Context Protocol.

Dieses Projekt ist keine eigenständige Genealogie-Benutzeroberfläche oder Ersatz für Gramps Web. Betreiben Sie es parallel zu einer bestehenden Gramps-Web-Instanz; Ihre Benutzer, Bäume, Medien, Berechtigungen und die Genealogie-Bearbeitungsoberfläche bleiben in Gramps Web.

Funktionen

• 57 MCP-Werkzeuge — Lesen, Erstellen, Aktualisieren und Löschen von Personen, Familien, Ereignissen, Orten, Quellen, Zitaten, Notizen, Medien, Repositorien und Tags

• Suche und Durchsuchen — Volltextsuche und paginierte Objektliste

• Verwandtschaftswerkzeuge — Vorfahren, Nachkommen, Beziehungen und Zeitachsen

• Zusammengesetzte Arbeitsabläufe — Person schnell hinzufügen, Ereignis zu Person hinzufügen, nach Gramps-ID suchen

• 6 MCP-Ressourcen — Typvokabulare, Eingabehilfe, Baum-Metadaten, Namenseinstellungen und optionale Medien-Thumbnails/Dateien für visionsfähige Agenten

• Medien-Sicherheitsvorkehrungen — Größenbeschränkungen, MIME-Whitelist und Standard-Ausblendung privater Datensätze

• MCP-Prompts — Geführte Arbeitsabläufe für Recherche, Hinzufügen von Personen/Familien und Importe

• Mehrere Transporte — stdio (lokale Clients), Streamable HTTP, Legacy SSE

• Nur-Lesen-Modus — Alle Werkzeuge sichtbar lassen, während Erstellungs-, Aktualisierungs- und Löschvorgänge blockiert werden

Das vollständige Werkzeugverzeichnis finden Sie im Tool-Katalog.

Related MCP server: ASPNET Core Debugging MCP Server

Voraussetzungen

• .NET 8 SDK (für lokale Entwicklung)

• Eine laufende Gramps Web-Instanz mit API-Zugriff

• Docker (optional, für Container-Bereitstellung)

Schnellstart

Lokale Entwicklung (Demo-Server)

run-local-server.sh verbindet sich mit der öffentlichen Instanz demo.grampsweb.org unter Verwendung der bekannten Demo-Anmeldedaten (owner / owner):

./run-local-server.sh

Der Server startet mit HTTP-Transport unter http://127.0.0.1:8080/mcp. Es ist kein API-Schlüssel erforderlich, wenn nur auf Loopback gebunden wird.

Docker

Vorgefertigte Multi-Arch-Images (linux/amd64, linux/arm64) werden im GitHub Container Registry veröffentlicht. Docker wählt automatisch die passende Architektur aus; amd64 deckt die meisten Unraid- und x86-Hosts ab, arm64 Apple Silicon und ARM-SBCs:

docker pull ghcr.io/scormave/gramps-web-mcp:latest

docker run -p 8080:8080 \
  -e GRAMPS_API_URL=https://your-gramps.example.com \
  -e GRAMPS_USERNAME=your-user \
  -e GRAMPS_PASSWORD=your-password \
  -e GRAMPS_TREE_ID=your-tree-uuid \
  -e MCP_API_KEY=your-secret-api-key \
  ghcr.io/scormave/gramps-web-mcp:latest

Das Image stellt einen GET /health-Endpunkt für Docker HEALTHCHECK, Unraid-Container-Health und andere Uptime-Monitore bereit. Es gibt HTTP 200 zurück, wenn der MCP-Server sich bei Gramps Web authentifizieren kann, ansonsten HTTP 503. Die öffentliche Antwort ist standardmäßig minimal: { "status": "healthy" } oder { "status": "unhealthy" }. Die Startprotokolle enthalten eine Zeile wie Connected to Gramps Web at …, sobald die API erreichbar ist.

Das Image verwendet standardmäßig Streamable HTTP (MCP_TRANSPORT=http) auf Port 8080, was die obigen Befehle nutzen. Clients, die den Container selbst starten (z. B. MCP Registry-Installationen), führen ihn stattdessen über stdio mit -e MCP_TRANSPORT=stdio und offenem stdin (docker run -i) aus; dieser Modus wird in server.json deklariert.

Für den Nur-Lesen-Modus fügen Sie -e GRAMPS_READ_ONLY=true hinzu:

docker run -p 8080:8080 \
  -e GRAMPS_API_URL=https://your-gramps.example.com \
  -e GRAMPS_USERNAME=your-user \
  -e GRAMPS_PASSWORD=your-password \
  -e GRAMPS_TREE_ID=your-tree-uuid \
  -e MCP_API_KEY=your-secret-api-key \
  -e GRAMPS_READ_ONLY=true \
  ghcr.io/scormave/gramps-web-mcp:latest

Unraid-Installation

Unraid-Benutzer können gramps-web-mcp aus den Community Applications installieren. Die Vorlagenquelle wird unter Scormave/gramps-web-mcp-unraid gepflegt. Für Unraid-spezifische Hilfe siehe den Support-Thread im Unraid-Forum.

Grundlegende Einrichtung:

1. Öffnen Sie in Unraid Apps / Community Applications.

2. Suchen Sie nach gramps-web-mcp und installieren Sie die Vorlage.

3. Setzen Sie GRAMPS_API_URL, GRAMPS_USERNAME, GRAMPS_PASSWORD und GRAMPS_TREE_ID für Ihre Gramps-Web-Instanz. Setzen Sie MCP_API_KEY, wenn der MCP-Port von anderen Maschinen in Ihrem Netzwerk erreichbar ist.

4. Behalten Sie den Standard-Container-Port 8080 bei oder ordnen Sie ihn einem anderen Host-Port zu.

5. Starten Sie den Container und prüfen Sie /health; es gibt HTTP 200 zurück, sobald der Dienst sich bei Gramps Web authentifizieren kann, standardmäßig mit einer minimalen JSON-Antwort.

Für die einfachste Kopplung betreiben Sie Gramps Web und gramps-web-mcp im selben Unraid-Docker-Netzwerk und setzen GRAMPS_API_URL auf die Container-URL von Gramps Web. Der MCP-Endpunkt für Clients ist http://<unraid-host>:<gemappter-port>/mcp.

Gramps Web + MCP (Docker Compose)

Um Gramps Web und den MCP-Server auf demselben Host und Docker-Netzwerk zu betreiben, verwenden Sie docker-compose.example.yml als Ausgangspunkt:

cp docker-compose.example.yml docker-compose.yml
cp .env.example .env
# Complete the Gramps Web setup wizard, then set credentials in .env
docker compose up -d

Gramps Web wird auf Port 5055 veröffentlicht; MCP auf 8080 (/mcp und /health). Innerhalb des Compose-Netzwerks erreicht der MCP-Container Gramps Web unter http://grampsweb:5000.

Claude Desktop (MCPB-Erweiterung)

Die Ein-Klick-Installation für Claude Desktop ist als MCP Bundle (.mcpb) über GitHub Releases verfügbar. Laden Sie das Bundle für Ihre Plattform herunter:

1. Laden Sie die .mcpb-Datei für Ihr Betriebssystem aus dem neuesten Release herunter.

2. Doppelklicken Sie darauf oder ziehen Sie sie in das Claude Desktop-Fenster.

3. Geben Sie Ihre Gramps-Web-URL, Benutzername, Passwort/Token und Baum-UUID ein.

4. Lassen Sie den Nur-Lesen-Modus für Ihre erste Sitzung aktiviert; deaktivieren Sie ihn nur, wenn Claude Datensätze erstellen oder bearbeiten soll.

5. Schließen Sie die Installation ab und starten Sie einen neuen Chat.

Die Erweiterung läuft lokal über stdio und benötigt das .NET SDK auf Ihrem Rechner nicht. Siehe mcpb/README.md für Verpackungsdetails und PRIVACY.md für die Datenschutzerklärung.

Um ein Bundle lokal zu erstellen:

./scripts/pack-mcpb.sh osx-arm64   # or osx-x64, win-x64, linux-x64, linux-arm64

MCP-Client-Konfiguration (manuell)

stdio (z. B. Claude Desktop, Cursor):

{
  "mcpServers": {
    "gramps-web": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/gramps-web-mcp/GrampsWeb.Mcp/GrampsWeb.Mcp.csproj"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "GRAMPS_API_URL": "https://your-gramps.example.com",
        "GRAMPS_USERNAME": "your-user",
        "GRAMPS_PASSWORD": "your-password",
        "GRAMPS_TREE_ID": "your-tree-uuid"
      }
    }
  }
}

Um einen stdio-Server im Nur-Lesen-Modus zu betreiben, fügen Sie "GRAMPS_READ_ONLY": "true" zu env hinzu.

HTTP (remote / Docker):

Richten Sie Ihren MCP-Client auf http://host:8080/mcp mit Streamable-HTTP-Transport. Wenn MCP_API_KEY gesetzt ist, senden Sie ihn als Authorization: Bearer <key> oder X-Api-Key: <key> bei jeder MCP-Anfrage.

curl -X POST http://host:8080/mcp \
  -H "Authorization: Bearer $MCP_API_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}},"id":1}'

Visionsfähige Agenten können optionale Medien über Werkzeuge (GetMediaThumbnail, GetMediaFile) oder über binäre MCP-Ressourcen wie gramps://media/{handle}/thumbnail/{size} und gramps://media/{handle}/file lesen. GetMediaFile gibt je nach MIME-Typ Bild-, Audio- oder eingebetteten Blob-Ressourcen-Inhalt zurück. Die End-to-End-Analyse hängt davon ab, dass der MCP-Client den typisierten Werkzeuginhalt oder binären Ressourceninhalt an ein fähiges Modell weiterleitet.

Konfiguration

Erforderlich (Gramps-Verbindung)

Laufzeitmodus

• GRAMPS_READ_ONLY: auf true setzen, um Erstellungs-, Aktualisierungs- und Löschaufrufe zu blockieren, während Werkzeuge sichtbar bleiben.

• GRAMPS_MUTATION_SERIALIZE: führt HTTP-Erstellungs-/Aktualisierungs-/Löschaufrufe nacheinander in diesem Prozess aus.

• GRAMPS_MUTATION_MIN_INTERVAL_MS: minimale Pause zwischen Mutations-HTTP-Aufrufen, einschließlich Schritten innerhalb zusammengesetzter Werkzeuge.

Laufzeithinweise:

• GRAMPS_READ_ONLY=false bedeutet, dass der Server im Lese-/Schreibmodus startet.

• Die Claude Desktop MCPB-Erweiterung ist die Ausnahme: Ihr Einrichtungsformular ist standardmäßig auf schreibgeschützt für eine sicherere erste Nutzung voreingestellt.

• Schreibserialisierung und das optionale Intervall schützen typische Gramps-Web-SQLite-Bäume vor Schreibstößen durch Agenten.

• Die Schreibsperre ist nur prozessintern. Sie koordiniert nicht über mehrere MCP-Replikate, die Gramps-Web-Benutzeroberfläche oder andere API-Clients hinweg.

• SQLite-Bereitstellungen, die bei sequenziellen Bearbeitungen weiterhin database is locked sehen, sollten GRAMPS_MUTATION_MIN_INTERVAL_MS=250 oder 500 setzen.

• Bei SQLite-Sperrfehlern oder upstream HTTP 429 geben Mutationswerkzeuge einen wiederholbaren MCP-Fehler mit einem kurzen Backoff-Hinweis anstelle eines generischen 500 zurück.

• Setzen Sie GRAMPS_MUTATION_SERIALIZE=false, wenn Gramps Web PostgreSQL verwendet und Sie parallele Schreibvorgänge wünschen.

Medien-Dateizugriff

Medien-Byte-Werkzeuge/Ressourcen sind standardmäßig deaktiviert. get_media bleibt für Metadaten verfügbar, ohne Dateidownloads zu aktivieren.

Bevorzugen Sie GetMediaThumbnail oder gramps://media/{handle}/thumbnail/{size} für die KI-Analyse. Vollständige Dateien können groß und sensibel sein und unterliegen weiterhin denselben Größen-, MIME- und Privatdatensatz-Prüfungen.

Exakte Typen und type/*-Wildcards werden unterstützt. Die Standard-Medien-Whitelist ist image/jpeg,image/png,image/webp,image/avif,application/pdf.

Transporte

Setzen Sie wie üblich GRAMPS_API_URL, GRAMPS_USERNAME, GRAMPS_PASSWORD und GRAMPS_TREE_ID.

Für HTTP-Transport werden Antworten über SSE gestreamt. Siehe die Streamable-HTTP-Spezifikation für Protokolldetails. Setzen Sie ASPNETCORE_URLS, um die Lauschadresse zu wählen, z. B. http://127.0.0.1:8080.

Optional (MCP-Transport)

HTTP-Authentifizierung

Wenn MCP_API_KEY gesetzt ist, erfordern alle MCP HTTP/SSE-Endpunkte den Schlüssel bei jeder Anfrage. GET /health bleibt anonym für Docker- und Load-Balancer-Überprüfungen.

Generieren Sie einen Schlüssel:

openssl rand -base64 32

Ohne einen Schlüssel startet der Server trotzdem (abwärtskompatibel). Wenn die Listen-Adresse nicht nur auf Loopback beschränkt ist, wird eine Warnung protokolliert, die empfiehlt, MCP_API_KEY zu setzen, einen Reverse-Proxy mit eigener Authentifizierung zu verwenden oder auf 127.0.0.1 für die lokale Nutzung zu binden.

Innerhalb von Docker ist ASPNETCORE_URLS typischerweise http://0.0.0.0:8080, sodass die Warnung auch dann erscheint, wenn der Host den Port nur auf 127.0.0.1 veröffentlicht. Das ist zu erwarten, wenn der externe Zugriff bereits eingeschränkt ist.

Entwicklung

dotnet test

Siehe CONTRIBUTING.md und die Entwickleranleitung.

Dokumentation

Mitwirken

Beiträge sind willkommen. Siehe CONTRIBUTING.md.

Sicherheit

Um eine Sicherheitslücke zu melden, siehe SECURITY.md.

Datenschutzerklärung

Die Claude Desktop-Erweiterung ist ein lokaler MCP-Server. Sie sendet Daten nur an die Gramps Web-Instanz, die Sie konfigurieren, und sammelt keine Analyse- oder Gesprächsdaten. Siehe PRIVACY.md für vollständige Details.

Lizenz

Copyright (c) Scormave

Dieses Projekt ist lizenziert unter der GNU Affero General Public License v3.0 (AGPL-3.0-or-later). Da es sich um Netzwerkserversoftware handelt, erfordert das Hosten einer modifizierten Version, den entsprechenden Quellcode für Benutzer verfügbar zu machen, die über ein Netzwerk mit ihr interagieren.