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

Klonen Sie das Graphiti GitHub-Repository

git clone https://github.com/getzep/graphiti.git

oder

gh repo clone getzep/graphiti

Notieren Sie den vollständigen Pfad zu diesem Verzeichnis.

cd graphiti && pwd

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

Installation

Voraussetzungen

Stellen Sie sicher, dass Sie Python 3.10 oder höher installiert haben.
Eine laufende Neo4j-Datenbank (Version 5.26 oder höher erforderlich)
OpenAI-API-Schlüssel für LLM-Operationen

Aufstellen

Klonen Sie das Repository und navigieren Sie zum Verzeichnis mcp_server
Verwenden Sie uv , um eine virtuelle Umgebung zu erstellen und Abhängigkeiten zu installieren:

# Install uv if you don't have it already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a virtual environment and install dependencies in one step
uv sync

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:

uv run graphiti_mcp_server.py

Mit Optionen:

uv run graphiti_mcp_server.py --model gpt-4.1-mini --transport sse

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:

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).
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:

docker compose up

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

docker-compose up

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 Installationsanweisungen .
Stellen Sie sicher, dass Sie den vollständigen Pfad zur uv Binärdatei und Ihrem Graphiti-Projektordner festlegen.

{
  "mcpServers": {
    "graphiti-memory": {
      "transport": "stdio",
      "command": "/Users/<user>/.local/bin/uv",
      "args": [
        "run",
        "--isolated",
        "--directory",
        "/Users/<user>>/dev/zep/graphiti/mcp_server",
        "--project",
        ".",
        "graphiti_mcp_server.py",
        "--transport",
        "stdio"
      ],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "password",
        "OPENAI_API_KEY": "sk-XXXXXXXX",
        "MODEL_NAME": "gpt-4.1-mini"
      }
    }
  }
}

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

{
  "mcpServers": {
    "graphiti-memory": {
      "transport": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

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:

add_episode(
name="Customer Profile",
episode_body="{\"company\": {\"name\": \"Acme Technologies\"}, \"products\": [{\"id\": \"P001\", \"name\": \"CloudSync\"}, {\"id\": \"P002\", \"name\": \"DataMiner\"}]}",
source="json",
source_description="CRM data"
)

Integration mit der Cursor-IDE

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

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

python graphiti_mcp_server.py --transport sse --use-custom-entities --group-id <your_group_id>

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

docker compose up

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

{
  "mcpServers": {
    "graphiti-memory": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Fügen Sie die Graphiti-Regeln zu den Benutzerregeln von Cursor hinzu. Weitere Informationen finden Sie in cursor_rules.md .
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.

Führen Sie den Graphiti MCP-Server mit SSE-Transport aus :
docker compose up
(Optional) Installieren Sie mcp-remote global : 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
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.
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.

Graphiti MCP Server