Graphiti MCP Server

Graphiti ist ein Framework zum Erstellen und Abfragen zeitabhängiger Wissensgraphen, das speziell auf KI-Agenten in dynamischen Umgebungen zugeschnitten ist. Im Gegensatz zu herkömmlichen Retrieval-Augmented-Generation-Methoden (RAG) integriert Graphiti kontinuierlich Benutzerinteraktionen, strukturierte und unstrukturierte Unternehmensdaten sowie externe Informationen in einen kohärenten, abfragbaren Graphen. Das Framework unterstützt inkrementelle Datenaktualisierungen, effiziente Abfragen und präzise historische Abfragen ohne vollständige Neuberechnung des Graphen und eignet sich daher für die Entwicklung interaktiver, kontextabhängiger KI-Anwendungen.

Dies ist eine experimentelle Serverimplementierung des Model Context Protocol (MCP) für Graphiti. Der MCP-Server stellt die wichtigsten Funktionen von Graphiti über das MCP-Protokoll bereit und ermöglicht KI-Assistenten die Interaktion mit den Wissensgraphenfunktionen von Graphiti.

Merkmale

Der Graphiti MCP-Server stellt die folgenden wichtigen High-Level-Funktionen von Graphiti bereit:

• Episodenverwaltung : Episoden (Text, Nachrichten oder JSON-Daten) hinzufügen, abrufen und löschen

• Entity Management : Suchen und verwalten Sie Entity-Knoten und -Beziehungen im Wissensgraphen

• Suchfunktionen : Suche nach Fakten (Kanten) und Knotenzusammenfassungen mithilfe der semantischen und hybriden Suche

• Gruppenverwaltung : Organisieren und verwalten Sie Gruppen verwandter Daten mit group_id-Filterung

• Graphenwartung : Löschen Sie den Graphen und erstellen Sie die Indizes neu

Schnellstart für Claude Desktop, Cursor und andere Clients

1. Klonen Sie das Graphiti GitHub-Repository

oder

Notieren Sie den vollständigen Pfad zu diesem Verzeichnis.

2. Installieren Sie die Graphiti-Voraussetzungen .

3. Konfigurieren Sie Claude, Cursor oder andere MCP-Clients für die Verwendung von Graphiti mit einem . Informationen zum Speicherort der MCP-Konfigurationsdateien finden Sie in der Clientdokumentation.

Installation

Voraussetzungen

1. Stellen Sie sicher, dass Sie Python 3.10 oder höher installiert haben.

2. Eine laufende Neo4j-Datenbank (Version 5.26 oder höher erforderlich)

3. OpenAI-API-Schlüssel für LLM-Operationen

Aufstellen

1. Klonen Sie das Repository und navigieren Sie zum Verzeichnis mcp_server

2. Verwenden Sie uv , um eine virtuelle Umgebung zu erstellen und Abhängigkeiten zu installieren:

Konfiguration

Der Server verwendet die folgenden Umgebungsvariablen:

• NEO4J_URI : URI für die Neo4j-Datenbank (Standard: bolt://localhost:7687 )

• NEO4J_USER : Neo4j-Benutzername (Standard: neo4j )

• NEO4J_PASSWORD : Neo4j-Passwort (Standard: demodemo )

• OPENAI_API_KEY : OpenAI-API-Schlüssel (erforderlich für LLM-Operationen)

• OPENAI_BASE_URL : Optionale Basis-URL für die OpenAI-API

• MODEL_NAME : Für LLM-Operationen zu verwendender OpenAI-Modellname.

• SMALL_MODEL_NAME : OpenAI-Modellname zur Verwendung für kleinere LLM-Operationen.

• LLM_TEMPERATURE : Temperatur für LLM-Antworten (0,0–2,0).

• AZURE_OPENAI_ENDPOINT : Optionale Azure OpenAI-Endpunkt-URL

• AZURE_OPENAI_DEPLOYMENT_NAME : Optionaler Azure OpenAI-Bereitstellungsname

• AZURE_OPENAI_API_VERSION : Optionale Azure OpenAI API-Version

• AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME : Optionaler Azure OpenAI-Einbettungsbereitstellungsname

• AZURE_OPENAI_EMBEDDING_API_VERSION : Optionale Azure OpenAI API-Version

• AZURE_OPENAI_USE_MANAGED_IDENTITY : Optionale Verwendung von Azure Managed Identities zur Authentifizierung

Sie können diese Variablen in einer .env Datei im Projektverzeichnis festlegen.

Ausführen des Servers

So führen Sie den Graphiti MCP-Server direkt mit uv aus:

Mit Optionen:

Verfügbare Argumente:

• --model : Überschreibt die Umgebungsvariable MODEL_NAME .

• --small-model : Überschreibt die Umgebungsvariable SMALL_MODEL_NAME .

• --temperature : Überschreibt die Umgebungsvariable LLM_TEMPERATURE .

• --transport : Wählen Sie die Transportmethode (sse oder stdio, Standard: sse)

• --group-id : Legt einen Namespace für den Graphen fest (optional). Falls nicht angegeben, wird standardmäßig „default“ verwendet.

• --destroy-graph : Wenn festgelegt, werden beim Start alle Graphiti-Diagramme zerstört.

• --use-custom-entities : Aktiviert die Entitätsextraktion mit den vordefinierten ENTITY_TYPES

Docker-Bereitstellung

Der Graphiti MCP-Server kann mit Docker bereitgestellt werden. Das Dockerfile verwendet uv für die Paketverwaltung und gewährleistet so eine konsistente Installation der Abhängigkeiten.

Umgebungskonfiguration

Bevor Sie das Docker Compose-Setup ausführen, müssen Sie die Umgebungsvariablen konfigurieren. Sie haben zwei Möglichkeiten:

1. Verwenden einer .env-Datei (empfohlen):

   • Kopieren Sie die bereitgestellte .env.example -Datei, um eine .env Datei zu erstellen:

     cp .env.example .env

   • Bearbeiten Sie die .env Datei, um Ihren OpenAI-API-Schlüssel und andere Konfigurationsoptionen festzulegen:

     # Required for LLM operations OPENAI_API_KEY=your_openai_api_key_here MODEL_NAME=gpt-4.1-mini # Optional: OPENAI_BASE_URL only needed for non-standard OpenAI endpoints # OPENAI_BASE_URL=https://api.openai.com/v1

   • Das Docker Compose-Setup ist so konfiguriert, dass diese Datei verwendet wird, sofern sie vorhanden ist (optional).

2. Umgebungsvariablen direkt verwenden :

   • Sie können die Umgebungsvariablen auch beim Ausführen des Docker Compose-Befehls festlegen:

     OPENAI_API_KEY=your_key MODEL_NAME=gpt-4.1-mini docker compose up

Neo4j-Konfiguration

Das Docker Compose-Setup umfasst einen Neo4j-Container mit der folgenden Standardkonfiguration:

• Benutzername: neo4j

• Passwort: demodemo

• URI: bolt://neo4j:7687 (innerhalb des Docker-Netzwerks)

• Für die Entwicklung optimierte Speichereinstellungen

Ausführen mit Docker Compose

Starten Sie die Dienste mit Docker Compose:

Oder wenn Sie eine ältere Version von Docker Compose verwenden:

Dadurch werden sowohl die Neo4j-Datenbank als auch der Graphiti MCP-Server gestartet. Das Docker-Setup:

• Verwendet uv für die Paketverwaltung und den Betrieb des Servers

• Installiert Abhängigkeiten aus der Datei pyproject.toml

• Stellt über die Umgebungsvariablen eine Verbindung zum Neo4j-Container her

• Stellt den Server auf Port 8000 für HTTP-basierten SSE-Transport bereit

• Beinhaltet einen Healthcheck für Neo4j, um sicherzustellen, dass es vor dem Starten des MCP-Servers voll funktionsfähig ist

Integration mit MCP-Clients

Konfiguration

Um den Graphiti MCP-Server mit einem MCP-kompatiblen Client zu verwenden, konfigurieren Sie ihn für die Verbindung mit dem Server:

[!WICHTIG] Sie benötigen den Python-Paketmanager uv . Bitte beachten Sie die uv .

Stellen Sie sicher, dass Sie den vollständigen Pfad zur uv Binärdatei und Ihrem Graphiti-Projektordner festlegen.

Für den SSE-Transport (HTTP-basiert) können Sie diese Konfiguration verwenden:

Verfügbare Tools

Der Graphiti MCP-Server stellt die folgenden Tools bereit:

• add_episode : Fügen Sie dem Wissensgraphen eine Episode hinzu (unterstützt Text-, JSON- und Nachrichtenformate)

• search_nodes : Durchsuchen Sie den Wissensgraphen nach relevanten Knotenzusammenfassungen

• search_facts : Durchsucht den Wissensgraphen nach relevanten Fakten (Kanten zwischen Entitäten)

• delete_entity_edge : Löscht eine Entitätskante aus dem Wissensgraphen

• delete_episode : Löscht eine Episode aus dem Wissensgraphen

• get_entity_edge : Ruft eine Entitätskante über ihre UUID ab.

• get_episodes : Holen Sie sich die neuesten Episoden für eine bestimmte Gruppe

• clear_graph : Alle Daten aus dem Wissensgraphen löschen und Indizes neu erstellen

• get_status : Ruft den Status des Graphiti MCP-Servers und der Neo4j-Verbindung ab

Arbeiten mit JSON-Daten

Der Graphiti MCP-Server kann strukturierte JSON-Daten über das Tool add_episode mit source="json" verarbeiten. Dadurch können Sie Entitäten und Beziehungen automatisch aus strukturierten Daten extrahieren:

Integration mit der Cursor-IDE

Um den Graphiti MCP-Server in die Cursor IDE zu integrieren, gehen Sie folgendermaßen vor:

1. Führen Sie den Graphiti MCP-Server mithilfe des SSE-Transports aus:

Hinweis: Geben Sie eine group_id an, um Graphdaten zu benennen. Wenn Sie keine group_id angeben, verwendet der Server „default“ als Gruppen-ID.

oder

2. Konfigurieren Sie Cursor für die Verbindung mit dem Graphiti MCP-Server.

3. Fügen Sie die Graphiti-Regeln zu den Benutzerregeln von Cursor hinzu. Weitere Informationen finden Sie in cursor_rules.md .

4. Starten Sie eine Agentensitzung in Cursor.

Die Integration ermöglicht es KI-Assistenten in Cursor, durch die Wissensgraphenfunktionen von Graphiti einen dauerhaften Speicher aufrechtzuerhalten.

Integration mit Claude Desktop (Docker MCP Server)

Der Graphiti MCP Server-Container verwendet den SSE MCP-Transport. Claude Desktop unterstützt SSE nicht nativ, daher müssen Sie ein Gateway wie mcp-remote verwenden.

1. Führen Sie den Graphiti MCP-Server mit SSE-Transport aus :

   docker compose up

2. (Optional) Installieren Sie : Wenn Sie mcp-remote lieber global installieren möchten oder Probleme beim Abrufen des Pakets durch npx auftreten, können Sie es global installieren. Andernfalls übernimmt npx (wird im nächsten Schritt verwendet) die Installation für Sie.

   npm install -g mcp-remote

3. Konfigurieren Sie Claude Desktop : Öffnen Sie Ihre Claude Desktop-Konfigurationsdatei (normalerweise claude_desktop_config.json ) und fügen Sie den Abschnitt mcpServers wie folgt hinzu oder ändern Sie ihn:

   { "mcpServers": { "graphiti-memory": { // You can choose a different name if you prefer "command": "npx", // Or the full path to mcp-remote if npx is not in your PATH "args": [ "mcp-remote", "http://localhost:8000/sse" // Ensure this matches your Graphiti server's SSE endpoint ] } } }

   Wenn Sie bereits einen mcpServers Eintrag haben, fügen Sie graphiti-memory (oder Ihren gewählten Namen) als neuen Schlüssel hinzu.

4. Starten Sie Claude Desktop neu, damit die Änderungen wirksam werden.

Anforderungen

• Python 3.10 oder höher

• Neo4j-Datenbank (Version 5.26 oder höher erforderlich)

• OpenAI-API-Schlüssel (für LLM-Operationen und -Einbettungen)

• MCP-kompatibler Client

Lizenz

Dieses Projekt unterliegt derselben Lizenz wie das übergeordnete Graphiti-Projekt.