Startseite / Artikel

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.

Verlag: REACTAPP.TOP8 Min. Lesezeit1743 Wörter

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 wie read-cypher in 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_USERNAME und NEO4J_PASSWORD zurü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 Allowed im 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 initialize und 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.
  • Der Server weigert sich zu starten und klagt über Anmeldeinformationen: NEO4J_USERNAME oder NEO4J_PASSWORD wurde im HTTP-Modus gesetzt. Entfernen Sie beide.
  • VS Code gibt an, der Server „erfordere Interaktion zum Starten“: mcp.json enthält weiterhin die stdio-Konfiguration. Wechseln Sie auf die http-Konfiguration.
  • Die Berechtigung zum Binden der Portnummer wird verweigert: Halten Sie 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

  • Private GitHub-Repos mit einem Token und Docker an Claude Desktop anschließen — Erstellen Sie ein klassisches GitHub-Token mit sicheren Berechtigungenskonfigurationen, fügen Sie den GitHub MCP-Server über Docker zu Claude Desktop hinzu, testen Sie ihn und nutzen Sie ihn für die Überprüfung von Pull Requests, die Priorisierung von Aufgaben sowie die Erstellung von Changelogs.