Führen Sie den Neo4j MCP Server auf Ihrem eigenen Rechner mit Docker und VS Code aus.
Hosten Sie Neo4j sowie seinen offiziellen MCP-Server selbst mit Docker Compose, sichern Sie sie mit Basic Auth über HTTP, verbinden Sie VS Code im Agent-Modus und abfragen Sie ein Demo-Graph.
Quellen: Run the Neo4j MCP Server Locally with Docker (No Codespaces Needed)
Neo4js offizieller MCP-Server ist ein kleines Programm, und der gesamte Stack kann mit Docker auf einem Laptop in etwa einer halben Stunde laufen. Das ist wichtig für alle, die den GraphAcademy-Kurs zur Entwicklung mit Neo4j MCP-Tools befolgen, denn der Kurs setzt GitHub Codespaces voraus, und Codespaces bietet nur eine monatliche kostenlose Nutzung, die irgendwann ausläuft. Durch Selbsthosting entfällt diese Beschränkung und es entstehen keine Kosten. Die unten aufgeführten Schritte wurden von Anfang bis Ende durchgeführt und zeigen außerdem, wie die einzelnen MCP-Komponenten zusammenpassen.
Was wird erstellt
VS Code (host) ──HTTP /mcp + auth──► neo4j-mcp (server) ──Bolt──► Neo4j (database)
Die Einrichtung setzt sich aus drei getrennten Komponenten zusammen, und das Klare Erkennen dieser Aufteilung erledigt den größten Teil der Arbeit.
- Host: der MCP-Client, beispielsweise VS Code, Claude Desktop oder Cursor. Er kümmert sich um das MCP-Protokoll und hat keine Ahnung von der Existenz von Neo4j.
- MCP-Server: die
neo4j-mcp-Brücke, die MCP-Toolaufrufe wieread-cypherin echte Bolt-Abfragen übersetzt. - Datenbank: Neo4j selbst.
Ein häufiger Irrtum ist, dass eine entfernte „MCP-Datenbank“ in der Cloud liegt. Das ist nicht der Fall. Der MCP-Server ist ein Programm, das lokal ausgeführt wird, und es verbindet sich nach außen mit der jeweiligen Datenbank, auf die es ausgerichtet ist.
Voraussetzungen
Docker Desktop muss installiert und im Lauf befinden sein, was durch docker --version bestätigt werden kann. Es wird VS Code mit MCP-Unterstützung sowie ein Terminal benötigt. Python und eine Neo4j-Installation sind nicht erforderlich, da Docker beides abdeckt.
Schritt 1: Die Docker-Stack-Struktur erstellen
Erstellen Sie ein Projektverzeichnis und fügen Sie eine Datei namens docker-compose.yml hinein. In dieser Datei werden zwei Dienste definiert. Zuerst kommt die Datenbank:
services:
neo4j:
image: neo4j:5.26
container_name: neo4j
ports:
- "7474:7474" # Neo4j Browser -> http://localhost:7474
- "7687:7687" # Bolt
environment:
NEO4J_AUTH: "neo4j/password123"
NEO4J_PLUGINS: '["apoc","graph-data-science"]' # needed for get-schema + GDS tool
volumes:
- neo4j_data:/data
healthcheck:
test: ["CMD-SHELL", "cypher-shell -u neo4j -p password123 'RETURN 1' || exit 1"]
interval: 10s
timeout: 10s
retries: 12
start_period: 30s
Zweitens kommt der MCP-Server, der direkt aus dem offiziellen Repository unter einem festgelegten Tag erstellt wird:
neo4j-mcp:
build:
context: "https://github.com/neo4j/mcp.git#v1.5.2" # builds the official server from source
container_name: neo4j-mcp
depends_on:
neo4j:
condition: service_healthy
ports:
- "8000:8000" # MCP endpoint -> http://localhost:8000/mcp
environment:
NEO4J_URI: "bolt://neo4j:7687"
NEO4J_DATABASE: "neo4j"
NEO4J_TRANSPORT_MODE: "http" # networked service, not a stdio subprocess
NEO4J_MCP_HTTP_HOST: "0.0.0.0" # bind all interfaces so the host can reach it
NEO4J_MCP_HTTP_PORT: "8000" # must be >1024 (container runs as non-root)volumes:
neo4j_data:
Zwei Details hier verdienen Aufmerksamkeit.
- HTTP-Transport anstelle von stdio. Der Kurs startet den Server im stdio-Modus, wobei der Host ihn als Kindprozess startet. Diese Umgebung führt ihn als eigenständigen HTTP-Dienst aus, was einer echten Bereitstellung näherkommt und es jedem Client ermöglicht, über eine URL anzuschließen.
- Warum diese Werte. Der Container verfügt nicht über Root-Rechte, weshalb das Binden eines privilegierten Ports unter 1024 fehlschlägt. Aus diesem Grund wird der Port 8000 anstelle von 80 verwendet. Im HTTP-Modus weist der Server aus Designgründen auch die Umgebungsvariablen
NEO4J_USERNAMEundNEO4J_PASSWORDzurück. Die Anmeldedaten werden mit jeder Anfrage über HTTP Basic Auth übermittelt, was dem Produktionsauthentifizierungsmodell entspricht, wodurch diese Variablen ungenutzt bleiben.
Schritt 2: Starten
docker compose up -d --build
Beim ersten Ausführen wird das Neo4j-Bild heruntergeladen, der Go MCP-Server kompiliert und die APOC- sowie GDS-Plugins heruntergeladen. Nach etwa einer Minute sollten beide Container aktiv sein:
docker compose ps
Warten Sie, bis neo4j (healthy) meldet.
Schritt 3: Den Server überprüfen
Der MCP-Endpunkt befindet sich unter http://localhost:8000/mcp. Wenn man ihn in einem Browser öffnet, erscheint die Meldung Method Not Allowed: only POST is supported. Das ist eigentlich beruhigend, denn es bedeutet, dass der Server aktiv ist und der Browser lediglich eine GET-Anfrage gesendet hat.
Verwenden Sie curl für einen ordentlichen Test. Beginnen Sie damit, zu überprüfen, ob eine Authentifizierung erforderlich ist:
curl -i -X POST http://localhost:8000/mcp # expect 401 Unauthorized
Dann listen Sie die Tools auf, während Sie sich mit den Datenbank-Zugangsdaten authentifizieren:
curl -s -u neo4j:password123 -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
http://localhost:8000/mcp
Die Antwort sollte get-schema, read-cypher und write-cypher nennen.
Warum nur drei Tools angezeigt werden
Der Kurs beschreibt vier Tools, und das fehlende ist list-gds-procedures. Es ist nichts kaputt. Dieses Tool wird erst während des MCP initialize-Handshakes verzögert registriert – und zwar nur, wenn Graph Data Science installiert ist. Eine einfache tools/list-Anfrage überspringt diesen Handshake, weshalb das vierte Tool nie angezeigt wird. Senden Sie zunächst initialize und listen Sie anschließend erneut auf:
curl -s -u neo4j:password123 -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}},"id":1}' \
http://localhost:8000/mcp
curl -s -u neo4j:password123 -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":2}' \
http://localhost:8000/mcp
Sie alle vier Tools sind jetzt sichtbar. Reale Clients wie VS Code führen initialize selbst aus, sodass dieses Problem nur rohe curl-Aufrufe betrifft.
Schritt 4: VS Code verbinden
Erstellen Sie .vscode/mcp.json im Projekt:
{
"servers": {
"neo4j": {
"type": "http",
"url": "http://localhost:8000/mcp",
"headers": {
"Authorization": "Basic bmVvNGo6cGFzc3dvcmQxMjM="
}
}
}
}
Der Authorization-Wert ist lediglich die Base64-Kodierung von neo4j:password123. Nach einem Passwortwechsel generieren Sie ihn erneut mit:
printf 'neo4j:yourpassword' | base64
Der häufigste Fehler besteht darin, die stdio-Konfiguration des Kurses ("type": "stdio", "command": "neo4j-mcp") auf diese Docker-Einrichtung anzuwenden. Dadurch wird VS Code angewiesen, ein lokales Binärdatei zu starten, das nicht existiert. Ein in Containern laufender Server benötigt die oben gezeigte http-Konfiguration.
In VS Code öffnen Sie das Befehlspalette mit Cmd/Ctrl + Shift + P, führen Sie MCP: List Servers aus, wählen Sie neo4j aus und klicken Sie auf Start Server. Anschließend wechseln Sie im Chat in den Agent-Modus (Cmd/Ctrl + Shift + I) und fordern Sie eine Liste der verfügbaren MCP-Tools mit IDs und Beschreibungen an. Es werden vier Tools zurückgegeben.
Schritt 5: In die Praxis umsetzen
Die lokale Datenbank beginnt leer, sodass ein zweiter, temporärer MCP-Container auf die öffentliche Movies-Demo-Datenbank von Neo4j verweisen kann – dieselbe, die im Kurs verwendet wird – über einen anderen Port. Der Hauptstack bleibt unverändert:
docker run --rm -d --name mcp-movies \
-e NEO4J_URI="neo4j+s://demo.neo4jlabs.com" \
-e NEO4J_DATABASE="recommendations" \
-e NEO4J_TRANSPORT_MODE="http" \
-e NEO4J_MCP_HTTP_HOST="0.0.0.0" \
-e NEO4J_MCP_HTTP_PORT="8001" \
-p 8001:8001 \
<your-project-name>-neo4j-mcp
Der Dateinamen ist derselbe, den docker compose erzeugt. Führen Sie docker images aus, um ihn anzusehen – er wird vermutlich yourfolder-neo4j-mcp lauten.
Um das Schema zu lesen und zu sehen, welche Beziehungen ein User hat, rufen Sie read-cypher auf:
curl -s -u recommendations:recommendations -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"read-cypher","arguments":{"query":"MATCH (u:User)-[r]->() RETURN DISTINCT type(r) AS rel"}},"id":2}' \
http://localhost:8001/mcp
Die Antwort ist RATED, was (:User)-[:RATED]->(:Movie) bedeutet.
Um eine Abfrage für den am höchsten bewerteten Film zu erstellen, muss ein Nicht-Null-Prüfungsfaktor eingefügt werden, da nicht jeder Film eine Bewertung hat:
curl -s -u recommendations:recommendations -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"read-cypher","arguments":{"query":"MATCH (m:Movie) WHERE m.imdbRating IS NOT NULL RETURN m.title AS title, m.imdbRating AS rating ORDER BY m.imdbRating DESC LIMIT 1"}},"id":3}' \
http://localhost:8001/mcp
Sobald die Demo beendet ist, stoppen Sie den Container:
docker stop mcp-movies
Schritt 6: Eine kleine Anwendung obenauf
Der Kurs endet damit, dass die Lernenden ein Python-Command-Line-Tool programmieren, das die fünf besten Filme eines Genres anzeigt. Diese vereinfachte Version übermittelt das Genre als Abfrageparameter – niemals durch Zeichenkettenverknüpfung – und filtert leere Bewertungen heraus:
import os, sys
from neo4j import GraphDatabase
QUERY = """
MATCH (m:Movie)-[:IN_GENRE]->(:Genre {name: $genre})
WHERE m.imdbRating IS NOT NULL
RETURN m.title AS title, m.imdbRating AS rating
ORDER BY m.imdbRating DESC
LIMIT 5
"""def main():
uri = os.environ["NEO4J_URI"]
user = os.environ["NEO4J_USERNAME"]
pwd = os.environ["NEO4J_PASSWORD"]
db = os.environ.get("NEO4J_DATABASE", "neo4j") genre = input("Enter a movie genre: ").strip()
with GraphDatabase.driver(uri, auth=(user, pwd)) as driver:
driver.verify_connectivity()
records, _, _ = driver.execute_query(QUERY, genre=genre, database_=db) print(f"\nTop {len(records)} '{genre}' movies:")
for i, r in enumerate(records, 1):
print(f" {i}. {r['title']} ({r['rating']})")if __name__ == "__main__":
main()
Testen Sie es an der Demo-Datenbank:
pip install neo4j
export NEO4J_URI="neo4j+s://demo.neo4jlabs.com"
export NEO4J_USERNAME="recommendations"
export NEO4J_PASSWORD="recommendations"
export NEO4J_DATABASE="recommendations"
python3 movie_recommender.py # then type: Mystery
Was erreicht wurde
Innerhalb von etwa einer halben Stunde läuft die vollständige Neo4j MCP-Stack-Infrastruktur lokal – ohne Codespaces und ohne Cloud-Kosten:
- Neo4j mit APOC und GDS sowie der offizielle
neo4j-mcp-Server, beides in Docker - Der MCP-Server als authentifizierte HTTP-Dienstleistung
- VS Code im Agent-Modus verbunden
- Echte Abfragen über die MCP-Tools sowie eine kleine Python-Anwendung darüber
Warum das Selbsthosting mehr beibringt
Man könnte dies leicht als Umgehung von Quoten interpretieren, doch das persönliche Betreiben des Servers zeigt etwas Nützlicheres. MCP entwickelt sich zur Standardmethode dafür, dass KI-Agenten auf reale Systeme zugreifen können: Datenbanken, APIs und interne Tools. Die interessanten ingenieurtechnischen Fragen tauchen genau dort auf, wo diese Konfiguration ansetzt. Wie wird der Server transportiert? Wie werden Anfragen authentifiziert? Was verhindert, dass ein Agent schädliche Abfragen ausführt?
Die Nutzung des Servers über HTTP mit Authentifizierung pro Anfrage sowie einem nur-Lese-Modus bringt diese Fragen an die Oberfläche, während eine vorgefertigte, gehostete Sandbox sie versteckt. Da Agenten zunehmend echte Produktionsdaten abrufen, ist es wichtiger, einen MCP-Server als kontrollierten, überwachbaren Dienst zu betreiben, anstatt einer Black Box zu vertrauen, die von jemand anderem gehostet wird. Dasselbe Prinzip gilt auch für eine echte Bereitstellung hinter einem Gateway mit TLS sowie einem Secrets-Manager.
Fehlerbehebung
Method Not Allowedim Browser: Die Anfrage war eine GET-Anfrage, während der Endpunkt nur POST-Anfragen akzeptiert. Verwenden Sie curl oder einen MCP-Client.401 Unauthorized: Die Basic Authentifizierung fehlt oder ist falsch. Verwenden Sie den Benutzernamen und das Passwort der Datenbank.- Nur drei Tools aufgelistet: Senden Sie zunächst den Befehl
initializeund stellen Sie sicher, dass APOC und GDS installiert sind.
get-schema fehlschlägt: APOC ist nicht installiert. Fügen Sie es zu NEO4J_PLUGINS hinzu.NEO4J_USERNAME oder NEO4J_PASSWORD wurde im HTTP-Modus gesetzt. Entfernen Sie beide.mcp.json enthält weiterhin die stdio-Konfiguration. Wechseln Sie auf die http-Konfiguration.NEO4J_MCP_HTTP_PORT über 1024, da der Container nicht als Root läuft.Weiterführende Literatur
Die Dokumentation zum Neo4j MCP-Server sowie die offizielle MCP-Spezifikation enthalten weitere Details.
Verwandte Literatur
- Sicheren Sie einen Spring AI MCP Server mit OAuth 2.0 und Tool-spezifischen Berechtigungsrahmen — Erstellen Sie einen OAuth-Autorisierungsserver und wandeln Sie einen Spring AI MCP Server in einen Ressourcenserver um, testen Sie ihn im MCP Inspector und beschränken Sie anschließend einzelne Tools durch Berechtigungsrahmen.
- Praktische Hinweise: Microsoft baute den Playwright MCP Server – und sagte Ihnen dann, was Sie tun sollen — Detaillierte Anleitung zu den Praktischen Hinweisen: Microsoft baute den Playwright MCP Server – und sagte Ihnen dann, was Sie tun sollen: Verträge, Überprüfungen sowie Code-Blöcke für Teams, die dieses Muster einsetzen.