Uruchom serwer MCP Neo4j na swoim komputerze za pomocą Dockera i VS Code
Zainstaluj Neo4j oraz jego oficjalny serwer MCP samodzielnie za pomocą Docker Compose, zabezpiecz je za pomocą autoryzacji typu Basic przez HTTP, połącz VS Code w trybie Agent i zapytaj grafikę demonstracyjną.
Źródła: Run the Neo4j MCP Server Locally with Docker (No Codespaces Needed)
Oficjalny serwer MCP firmy Neo4j to niewielki program, a cały stack może zostać uruchomiony na laptopie z Dockerem w mniej więcej pół godziny. Jest to istotne dla wszystkich, którzy uczestniczą w kursie GraphAcademy dotyczącym tworzenia narzędzi z użyciem MCP w Neo4j, ponieważ kurs zakłada użycie GitHub Codespaces, a ten oferuje miesięczną darmową pulę, która w końcu się wyczerpuje. Samodzielne hostowanie eliminuje ten limit i nie wiąże się z żadnymi kosztami. Poniższe kroki zostały przeprowadzone od początku do końca i pokazują również, jak poszczególne elementy MCP ze sobą współpracują.
Co zostanie stworzone
VS Code (host) ──HTTP /mcp + auth──► neo4j-mcp (server) ──Bolt──► Neo4j (database)
Składanie tego rozwiązania polega na trzech oddzielnych komponentach, a jasne zrozumienie ich roli pomaga w większości przypadków.
- Host: klient MCP, na przykład VS Code, Claude Desktop lub Cursor. Obsługuje protokół MCP i nie ma pojęcia o istnieniu Neo4j.
- Server MCP: mostek
neo4j-mcp, który przekształca wywołania narzędzi MCP, takie jakread-cypher, w rzeczywiste zapytania Bolt. - Baza danych: sam Neo4j.
Częstym błędem jest przekonanie, że jakaś zdalna „baza danych MCP” znajduje się w chmurze. Tak nie jest. Server MCP to program uruchamiany lokalnie, który łączy się z tą bazą danych, do której jest skierowany.
Wymagania wstępne
Należy zainstalować i uruchomić Docker Desktop, co potwierdza polecenie docker --version. Potrzebny jest VS Code z obsługą MCP oraz terminal. Python i Neo4j nie są wymagane, ponieważ Docker obejmuje je oba.
Krok 1: Stworzenie stacka Docker
Stwórz folder projektu i umieść w nim plik docker-compose.yml. Plik ten definiuje dwa usługi. Najpierw jest baza danych:
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
Na drugim miejscu znajduje się serwer MCP, stworzony bezpośrednio z oficjalnego repozytorium przy użyciu określonego tagu:
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:
Dwa szczegóły tutaj wymagają uwagi.
- Transport HTTP zamiast stdio. Kurs uruchamia serwer w trybie stdio, gdzie host uruchamia go jako proces potomny. Ten układ działający w trybie HTTP jest bardziej zbliżony do rzeczywistego wdrożenia i umożliwia połączenie się dowolnego klienta za pomocą adresu URL.
- Dlaczego te wartości. Kontener nie ma uprawnień root, więc próba przydzielenia uprzywilejowanego portu poniżej 1024 kończy się niepowodzeniem. Z tego powodu port 8000 zastępuje port 80. W trybie HTTP serwer zgodnie z projektem odrzuca również zmienne środowiskowe
NEO4J_USERNAMEiNEO4J_PASSWORD. Dane uwierzytelniające są przekazywane z każdym żądaniem za pomocą autoryzacji HTTP Basic Auth, co odpowiada modelowi autoryzacji w środowisku produkcyjnym, dlatego te zmienne nie są używane.
Krok 2: Uruchomienie
docker compose up -d --build
Pierwsze uruchomienie pobiera obraz Neo4j, kompiluje serwer MCP w języku Go oraz ściąga plaginy APOC i GDS. Po około minucie sprawdź, czy oba kontenery są uruchomione:
docker compose ps
Poczekaj, aż neo4j poinformuje o stanie (healthy).
Krok 3: Sprawdzenie serwera
Endpoint MCP znajduje się pod adresem http://localhost:8000/mcp. Otwarcie go w przeglądarce powoduje komunikat Method Not Allowed: only POST is supported. To w rzeczywistości jest pocieszające, ponieważ oznacza, że serwer działa, a przeglądarka wysłała po prostu żądanie typu GET.
Aby przeprowadzić prawidłową próbę, użyj curl. Najpierw upewnij się, że wymagana jest autoryzacja:
curl -i -X POST http://localhost:8000/mcp # expect 401 Unauthorized
Następnie wymień narzędzia podczas autoryzacji za pomocą danych do bazy danych:
curl -s -u neo4j:password123 -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
http://localhost:8000/mcp
Odpowiedź powinna wymieniać get-schema, read-cypher oraz write-cypher.
Dlaczego widnieją tylko trzy narzędzia
Kurs opisuje cztery narzędzia, a brakujące to list-gds-procedures. Nic nie jest nieprawidłowe. To narzędzie jest rejestrowane w sposób opóźniony podczas procedury initialize MCP, i to tylko wtedy, gdy zainstalowano Graph Data Science. Prośba typu tools/list pomija tę procedurę, dlatego czwarte narzędzie nigdy się nie pojawia. Najpierw należy wysłać komendę initialize, a następnie ponownie wyświetlić listę:
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
Teraz widoczne są wszystkie cztery narzędzia. Prawdziwe klienty, takie jak VS Code, uruchamiają initialize samodzielnie, więc ta specyfika dotyczy tylko surowych wywołań curl.
Krok 4: Połączenie z VS Code
Stwórz plik .vscode/mcp.json w projekcie:
{
"servers": {
"neo4j": {
"type": "http",
"url": "http://localhost:8000/mcp",
"headers": {
"Authorization": "Basic bmVvNGo6cGFzc3dvcmQxMjM="
}
}
}
}
Wartość Authorization to po prostu kodowanie Base64 dla neo4j:password123. Po zmianie hasła należy je ponownie wygenerować za pomocą:
printf 'neo4j:yourpassword' | base64
Najczęstszym błędem jest ponowne użycie konfiguracji stdio kursu ("type": "stdio", "command": "neo4j-mcp") w tym ustawieniu Dockera. To każe VS Code uruchomić lokalny plik binarny, który nie istnieje. Serwer w kontenerze wymaga konfiguracji http pokazanej powyżej.
W VS Code otwórz panel poleceń przy użyciu Cmd/Ctrl + Shift + P, uruchom MCP: List Servers, wybierz neo4j i kliknij Start Server. Następnie przełącz Chat na tryb Agent (Cmd/Ctrl + Shift + I) i poproś o listę dostępnych narzędzi MCP wraz z ich identyfikatorami i opisami. Zwrócone zostaną cztery narzędzia.
Krok 5: Wykorzystanie
Baza danych lokalna zaczyna się pusta, więc drugi, tymczasowy kontener MCP może odwoływać się do publicznej bazy demonstracyjnej filmów Neo4j, tej samej, której używa kurs, ale na innym porcie. Główna struktura pozostaje nienaruszona:
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
Nazwa obrazu jest taka, jaką ustalił docker compose. Uruchom docker images, aby ją zobaczyć – powinna wyglądać mniej więcej jak twojafoldera-neo4j-mcp.
Aby przeczytać schemat i zobaczyć, jakie relacje ma User, wywołaj read-cypher:
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
Odpowiedź to RATED, co oznacza (:User)-[:RATED]->(:Movie).
Aby utworzyć zapytanie dotyczące najwyżej ocenionego filmu, należy dodać warunek sprawdzający, czy wartość nie jest pusta, ponieważ nie każdy film ma ocenę:
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
Gdy demo się zakończy, zatrzymaj kontener:
docker stop mcp-movies
Krok 6: Mała aplikacja na górze
Kurs kończy się tym, że uczestnicy tworzą narzędzie w wersji konsolowej w Pythonie, które wyświetla pięć najlepszych filmów danego gatunku. Ta lżejsza wersja przekazuje gatunek jako parametr zapytania, nigdy poprzez łączenie ciągów znaków, oraz filtruje oceny null:
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()
Zastosuj to do bazy danych demo:
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
Co udało się osiągnąć
W ciągu około pół godziny cały stos Neo4j MCP działa lokalnie, bez potrzeby korzystania z Codespaces i bez rachunku za chmurę:
- Neo4j z APOC i GDS, a także oficjalny serwer
neo4j-mcp, oba w Dockerze - Serwer MCP jako zautoryzowana usługa HTTP
- VS Code połączone w trybie Agent
- Rzeczywiste zapytania przesyłane za pomocą narzędzi MCP oraz małej aplikacji w Pythonie
Dlaczego samodzielne hostowanie uczy więcej
Można by to potraktować jako sposób na obejście ograniczeń, ale osobiste uruchomienie serwera pokazuje coś znacznie bardziej przydatnego. MCP staje się standardowym sposobem, dzięki któremu agenci AI mogą uzyskać dostęp do rzeczywistych systemów: baz danych, API i narzędzi wewnętrznych. Interesujące pytania inżynieryjne pojawiają się właśnie w tym miejscu – jak serwer jest transportowany? Jak autoryzowane są żądania? Co zapobiega temu, by agent wykonał destrukcyjne zapytanie?
Uruchamianie serwera przez HTTP, z autoryzacją na poziomie każdej prośby oraz trybem tylko do odczytu, sprawia, że te pytania wychodzą na powierzchnię, podczas gdy gotowe, hostowane środowiska izolowane je ukrywają. Ponieważ agenty coraz częściej obsługują dane z rzeczywistych środowisk produkcyjnych, istotne jest uruchamianie serwera MCP jako kontrolowanego, obserwowalnego usługi, zamiast polegać na czarnej skrzynce hostowanej przez kogoś innego. Ten sam podejście ma zastosowanie przy rzeczywistym wdrożeniu za bramką z TLS oraz menedżerem sekretów.
Rozwiązywanie problemów
Method Not Allowedw przeglądarce: prośba była typu GET, a endpoint przyjmuje tylko POST. Użyj curl lub klienta MCP.401 Unauthorized: brakuje lub jest błędny mechanizm autoryzacji Basic Auth. Użyj nazwy użytkownika i hasła z bazy danych.- Wymieniono tylko trzy narzędzia: najpierw wyślij polecenie
initializei upewnij się, że zainstalowane są APOC i GDS.
get-schema nie działa: Nie zainstalowano APOC. Dodaj je do NEO4J_PLUGINS.NEO4J_USERNAME lub NEO4J_PASSWORD. Usuń oba te wartości.mcp.json nadal zawiera konfigurację stdio. Przełącz się na wersję http.NEO4J_MCP_HTTP_PORT powyżej 1024, ponieważ kontener nie ma uprawnień root.Dalsza lektura
Dokumentacja serwera Neo4j MCP oraz oficjalna specyfikacja MCP zawierają szczegółowe informacje.
Powiązane materiały
- Zabezpieczanie serwera Spring AI MCP za pomocą OAuth 2.0 i zakresów dostępu dla poszczególnych narzędzi — Stworzenie serwera autoryzacji OAuth oraz przekształcenie serwera Spring AI MCP w serwer zasobów, przetestowanie go w MCP Inspector, a następnie ograniczenie dostępu do poszczególnych narzędzi za pomocą zakresów.
- Praktyczne notatki: Microsoft stworzył serwer MCP Playwright. A potem powiedział wam, co robić — Szczegółowy przewodnik po praktycznych notatkach: Microsoft stworzył serwer MCP Playwright. A potem powiedział wam, co robić: umowy, sprawdzenia oraz gotowe fragmenty kodu dla zespołów wdrażających ten wzorzec.