Neo4j MCP

Ein Model Context Protocol-Server, mit dem Claude (und andere MCP-Clients) Neo4j-Graphdatenbanken abfragen und verändern können. Er wird sowohl als eigenständiger MCP-Server als auch als Claude Code-Plugin ausgeliefert, das Sie einmal installieren und in jedem Projekt wiederverwenden können.

Jedes Projekt stellt seine eigenen Neo4j-Anmeldedaten über eine lokale .env-Datei bereit, sodass dasselbe Plugin auf verschiedene Datenbanken zugreifen kann, je nachdem, in welchem Ordner Claude Code geöffnet wird.

Funktionen

• Ein konsolidiertes cypher_query-Tool mit explizitem read / write-Modus.

• Schema-Introspektion: Labels, Beziehungstypen und Eigenschaftsschlüssel.

• Vollständige Serialisierung der Ergebnisse – bewahrt element_id von Knoten/Beziehungen, Labels, Typen sowie temporale/spatiale Neo4j-Werte.

• Ergebnisgrößenbegrenzung mit Abschneide-Flag, damit ein unkontrolliertes MATCH (n) die Antwort nicht sprengt.

• Projektbezogene Anmeldedaten über .env (geladen durch python-dotenv aus dem Arbeitsverzeichnis).

• Funktioniert mit stdio (Claude Code, Claude Desktop, Cursor) und SSE.

Related MCP server: neo4j-server-remote

Voraussetzungen

• Python 3.10+

• Eine erreichbare Neo4j-Datenbank (lokal, Docker oder Aura)

• pip (oder uv, pipx)

Installation des Python-Pakets

Das Plugin greift auf ein Konsolenskript namens neo4j-mcp-server zu, daher muss sich das Paket zuerst in Ihrem PATH befinden.

git clone https://github.com/your-repo/neo4j-mcp.git
cd neo4j-mcp
pip install -e .

Überprüfen Sie, ob es erfolgreich installiert wurde:

which neo4j-mcp-server
neo4j-mcp-server --help

Tipp: Wenn Sie pipx verwenden, hält pipx install -e . den Server von Ihrem globalen Python isoliert.

Verwendung als Claude Code-Plugin

Das Repository enthält ein Plugin-Manifest unter .claude-plugin/plugin.json. Sobald es auf Benutzerebene installiert ist, ist der neo4j MCP-Server in jeder Claude Code-Sitzung und in jedem Projekt verfügbar.

1. Installation des Plugins

Innerhalb von Claude Code:

/plugin install /absolute/path/to/neo4j-mcp

Dies registriert das Manifest global. (Sie können es auch über einen Marktplatz hinzufügen, falls Sie eines veröffentlichen – siehe die Plugin-Dokumentation von Claude Code.)

2. Erstellen Sie eine .env in jedem Projekt, das mit Neo4j kommunizieren soll

Der MCP-Server erbt das Arbeitsverzeichnis von Claude Code, sodass python-dotenv jede .env-Datei erkennt, die sich im Stammverzeichnis des Projekts befindet. Verschiedene Ordner → verschiedene Datenbanken, keine Neukonfiguration des Plugins erforderlich.

# my-project/.env
NEO4J_HOST=localhost
NEO4J_PORT=7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-secret
NEO4J_DATABASE=neo4j

Für Aura / verschlüsselte Verbindungen:

NEO4J_HOST=xxx.databases.neo4j.io
NEO4J_PORT=7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-aura-password
NEO4J_URI_SCHEME=neo4j+s
NEO4J_ENCRYPTED=true

Für eine nicht authentifizierte lokale Instanz lassen Sie NEO4J_USERNAME und NEO4J_PASSWORD leer.

Committen Sie niemals .env. Fügen Sie es in jedem Projekt zur .gitignore hinzu.

3. Verwendung mit Claude Code

Öffnen Sie das Projekt und stellen Sie Claude Fragen wie:

• "Welche Labels und Beziehungstypen existieren in diesem Graphen?"

• "Finde die 10 am stärksten vernetzten Person-Knoten."

• "Erstelle einen Movie-Knoten mit dem Titel Inception, der 2010 veröffentlicht wurde."

Claude wird bei Bedarf die Tools cypher_query, get_database_schema und test_database_connection aufrufen.

Verwendung ohne Claude Code

Das gleiche Paket funktioniert als einfacher MCP-Server für jeden MCP-kompatiblen Client.

Claude Desktop / Cursor

Fügen Sie dies zu ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) oder Ihrer Cursor MCP-Konfiguration hinzu:

{
  "mcpServers": {
    "neo4j": {
      "command": "neo4j-mcp-server",
      "args": []
    }
  }
}

Legen Sie die Anmeldedaten fest, indem Sie entweder eine .env-Datei dort ablegen, wo der Client den Prozess startet, oder indem Sie NEO4J_*-Variablen im Umgebungsblock exportieren.

SSE-Transport (Web-Clients)

neo4j-mcp-server --transport sse --host 0.0.0.0 --port 3000

Standalone-CLI

Ein kleiner Client ist für einmalige Tests enthalten:

neo4j-mcp-client --test
neo4j-mcp-client --schema
neo4j-mcp-client --query "MATCH (n) RETURN count(n) AS nodes"
neo4j-mcp-client --write --query "CREATE (p:Person {name: 'Alice'}) RETURN p"

Konfigurationsreferenz

Alle Einstellungen werden aus Umgebungsvariablen (oder einer .env-Datei im Arbeitsverzeichnis) gelesen.

Vom MCP-Server bereitgestellte Tools

Ressourcen: neo4j://schema, neo4j://connection. Prompt: cypher_query_help.

Entwicklung

pip install -e ".[dev]"
pytest                    # 21 unit tests, no live database needed
ruff check src/ tests/
mypy src/neo4j_mcp/

Fehlerbehebung

• Neo4j authentication failed — Benutzername/Passwort stimmen nicht überein. Lassen Sie bei nicht authentifizierten Datenbanken beide Felder leer (setzen Sie sie nicht auf neo4j/neo4j).

• Neo4j service unavailable — Die Datenbank ist ausgefallen oder NEO4J_HOST / NEO4J_PORT sind falsch. Versuchen Sie cypher-shell -a bolt://$NEO4J_HOST:$NEO4J_PORT, um dies zu bestätigen.

• Plugin kann neo4j-mcp-server nicht finden — das Konsolenskript befindet sich nicht im PATH, den Claude Code erbt. Installieren Sie es mit pipx oder stellen Sie sicher, dass Ihre Shell-RC-Datei den richtigen PATH für GUI-Apps exportiert. Unter macOS lesen GUI-Apps nicht ~/.zshrc; verwenden Sie launchctl setenv PATH ... oder installieren Sie es in /usr/local/bin.

• truncated: true bei einer Leseabfrage — erhöhen Sie das limit im Aufruf oder setzen Sie NEO4J_DEFAULT_RESULT_LIMIT in der .env höher.

MIT-lizenziert.