Exécutez le serveur MCP de Neo4j sur votre propre machine à l’aide de Docker et de VS Code
Hébergez vous-même Neo4j ainsi que son serveur MCP officiel à l’aide de Docker Compose, sécurisez-les avec une authentification de base via HTTP, connectez VS Code en mode Agent et interrogez un graphe de démonstration.
Sources: Run the Neo4j MCP Server Locally with Docker (No Codespaces Needed)
Le serveur MCP officiel de Neo4j est un petit programme, et l’ensemble du stack peut être exécuté sur un ordinateur portable avec Docker en environ une demi-heure. Cela est important pour quiconque suit le cours GraphAcademy sur le développement avec des outils MCP de Neo4j, car ce cours suppose l’utilisation de GitHub Codespaces, dont la limite mensuelle gratuite finit par s’épuiser. L’hébergement auto-géré élimine cette limite et ne coûte rien. Les étapes ci-dessous ont été exécutées du début à la fin, et elles montrent également comment les composants de MCP s’assemblent.
Ce qui est mis en place
VS Code (host) ──HTTP /mcp + auth──► neo4j-mcp (server) ──Bolt──► Neo4j (database)
La configuration se compose de trois éléments distincts, et comprendre clairement cette séparation suffit pour bien fonctionner.
- Hôte : le client MCP, par exemple VS Code, Claude Desktop ou Cursor. Il gère le protocole MCP sans avoir connaissance de l’existence de Neo4j.
- Serveur MCP : le pont
neo4j-mcp, qui traduit les appels d’outils MCP tels queread-cypheren vraies requêtes Bolt. - Base de données : Neo4j lui-même.
Une idée fausse courante est que certaine « base de données MCP » distante se trouve dans le cloud. Ce n’est pas le cas. Le serveur MCP est un programme exécuté localement, qui se connecte ensuite à la base de données ciblée.
Prérequis
Docker Desktop doit être installé et en cours d’exécution, ce que confirme la commande docker --version. Un VS Code prenant en charge MCP est nécessaire, ainsi qu’un terminal. Python et Neo4j ne sont pas requis, car Docker gère déjà les deux.
Étape 1 : Écrire la pile Docker
Créez un dossier de projet et placez-y un fichier docker-compose.yml. Ce fichier définit deux services. Le premier concerne la base de données :
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
En deuxième position vient le serveur MCP, construit directement à partir du répertoire officiel à une étiquette fixe :
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:
Deux détails ici méritent une attention particulière.
- Transport HTTP au lieu de stdio. Le cours lance le serveur en mode stdio, où l’hôte le démarre en tant que processus enfant. Cette approche le fait fonctionner en tant que service HTTP indépendant, ce qui est plus proche d’un déploiement réel et permet à n’importe quel client de se connecter via une URL.
- Pourquoi ces valeurs. Le conteneur n’a pas les droits root, donc l’association d’un port privilégié inférieur à 1024 échoue. C’est pour cette raison que le port 8000 remplace le port 80. En mode HTTP, le serveur refuse également, par conception, les variables d’environnement
NEO4J_USERNAMEetNEO4J_PASSWORD. Les identifiants sont transmis avec chaque requête via l’authentification HTTP Basic, ce qui correspond au modèle d’authentification en production, ce qui explique pourquoi ces variables ne sont pas utilisées.
Étape 2 : Le démarrer
docker compose up -d --build
La première exécution télécharge l’image Neo4j, compile le serveur MCP en Go et télécharge les plugins APOC et GDS. Après environ une minute, vérifiez que les deux conteneurs sont en cours d’exécution :
docker compose ps
Attendez que neo4j indique (healthy).
Étape 3 : Vérifier le serveur
L’endpoint MCP se trouve à l’adresse http://localhost:8000/mcp. Lorsqu’on l’ouvre dans un navigateur, on obtient Method Not Allowed: only POST is supported. Cela est en fait rassurant, car cela signifie que le serveur est opérationnel et que le navigateur a simplement envoyé une requête GET.
Utilisez curl pour effectuer un test correct. Commencez par confirmer que l’authentification est exigée :
curl -i -X POST http://localhost:8000/mcp # expect 401 Unauthorized
Ensuite, énumérez les outils en vous authentifiant avec les identifiants de la base de données :
curl -s -u neo4j:password123 -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
http://localhost:8000/mcp
La réponse doit mentionner get-schema, read-cypher et write-cypher.
Pourquoi seulement trois outils apparaissent-ils
Le cours décrit quatre outils, et le manquant est list-gds-procedures. Rien n’est cassé. Cet outil est enregistré de manière différée lors de la procédure initialize MCP, et uniquement lorsque Graph Data Science est installé. Une demande simple tools/list passe outre cette procédure, ce qui fait que le quatrième outil n’apparaît jamais. Envoyez d’abord initialize puis listez à nouveau :
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
Tous les quatre outils apparaissent maintenant. Les clients réels comme VS Code exécutent eux-mêmes initialize, donc ce problème ne concerne que les appels curl bruts.
Étape 4 : Connecter VS Code
Créez .vscode/mcp.json dans le projet :
{
"servers": {
"neo4j": {
"type": "http",
"url": "http://localhost:8000/mcp",
"headers": {
"Authorization": "Basic bmVvNGo6cGFzc3dvcmQxMjM="
}
}
}
}
La valeur Authorization n’est rien d’autre que l’encodage base64 de neo4j:password123. Après un changement de mot de passe, la régénérer avec :
printf 'neo4j:yourpassword' | base64
La erreur la plus fréquente consiste à réutiliser la configuration stdio du cours ("type": "stdio", "command": "neo4j-mcp") avec cette configuration Docker. Cela indique à VS Code de lancer un binaire local qui n’existe pas. Un serveur conteneurisé a besoin de la configuration http présentée ci-dessus.
Dans VS Code, ouvrez la palette de commandes avec Cmd/Ctrl + Shift + P, exécutez MCP: List Servers, sélectionnez neo4j puis choisissez Start Server. Ensuite, passez Chat en mode Agent (Cmd/Ctrl + Shift + I) et demandez une liste des outils MCP disponibles, avec leurs IDs et descriptions. Quatre outils sont retournés.
Étape 5 : L’utiliser
La base de données locale commence vide, ce qui permet à un deuxième conteneur MCP temporaire de faire référence à la base de données de démonstration publique de Neo4j consacrée aux films, celle même utilisée dans le cours, mais sur un port différent. La pile principale reste inchangée :
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
Le nom de l’image est celui généré par docker compose. Exécutez docker images pour le voir ; vous devriez obtenir quelque chose comme yourfolder-neo4j-mcp.
Pour lire le schéma et voir quels relations possède un User, appelez 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
La réponse est RATED, ce qui signifie (:User)-[:RATED]->(:Movie).
Pour générer une requête concernant le film le mieux noté, il faut inclure une vérification pour s’assurer que la valeur n’est pas nulle, car tous les films ne disposent pas de note :
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
Lorsque la démonstration est terminée, arrêtez le conteneur :
docker stop mcp-movies
Étape 6 : Une petite application en plus
Le cours se termine par la création, par les apprenants, d’un outil en ligne de commande en Python qui affiche les cinq meilleurs films d’un genre donné. Cette version simplifiée transmet le genre en tant que paramètre de requête, jamais par concaténation de chaînes, et filtre les notes nulles :
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()
Exécutez-le sur la base de données de démonstration :
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
Ce qui a été accompli
En environ une demi-heure, l’ensemble de la pile MCP de Neo4j fonctionne localement, sans Codespaces et sans facture cloud :
- Neo4j avec APOC et GDS, ainsi que le serveur officiel
neo4j-mcp, tous deux dans Docker - Le serveur MCP en tant que service HTTP authentifié
- VS Code connecté en mode Agent
- Des requêtes réelles via les outils MCP et une petite application Python en complément
Pourquoi l’hébergement propre enseigne davantage
On pourrait facilement interpréter cela comme un moyen de contourner des quotas, mais exécuter le serveur soi-même montre quelque chose de bien plus utile. MCP devient la voie standard permettant aux agents IA d’accéder à des systèmes réels : bases de données, API et outils internes. Les questions d’ingénierie intéressantes se posent précisément là où se situe cette configuration. Comment le serveur est-il transporté ? Comment les requêtes sont-elles authentifiées ? Qu’est-ce qui empêche un agent d’exécuter une requête destructrice ?
Le fait de faire fonctionner le serveur via HTTP, avec une authentification par requête et un mode lecture seule, soulève ces questions, tandis qu’un environnement sandbox hébergé prédéfini les cache. Étant donné que des agents traitent de plus en plus de données de production réelles, il est plus important de faire fonctionner un serveur MCP en tant que service contrôlé et observable que de faire confiance à une boîte noire hébergée par quelqu’un d’autre. La même logique s’applique à un déploiement réel derrière un pare-feu avec TLS et un gestionnaire de secrets.
Résolution de problèmes
Method Not Alloweddans le navigateur : la requête était de type GET alors que l’endpoint ne prend que des requêtes POST. Utilisez curl ou un client MCP.401 Unauthorized: l’authentification de base est manquante ou incorrecte. Utilisez le nom d’utilisateur et le mot de passe de la base de données.- Seuls trois outils listés : envoyez d’abord la commande
initialize, et assurez-vous que APOC et GDS sont installés.
get-schema échoue : APOC n’est pas installé. Ajoutez-le à NEO4J_PLUGINS.NEO4J_USERNAME ou NEO4J_PASSWORD a été défini en mode HTTP. Supprimez-les tous les deux.mcp.json contient encore la configuration stdio. Utilisez plutôt celle en mode http.NEO4J_MCP_HTTP_PORT au-dessus de 1024, car le conteneur n’a pas les droits root.Liens utiles
La documentation du serveur MCP de Neo4j ainsi que la spécification officielle MCP détaillent ces aspects.
Lectures complémentaires
- Sécuriser un serveur Spring AI MCP avec OAuth 2.0 et des scopes par outil — Créer un serveur d’autorisation OAuth et transformer un serveur Spring AI MCP en serveur de ressources, le tester dans MCP Inspector, puis restreindre certains outils en fonction de leurs scopes.
- Notes pratiques : Microsoft a construit le serveur MCP Playwright. Puis il vous a dit de le faire — Guide pas à pas des Notes pratiques : Microsoft a construit le serveur MCP Playwright. Puis il vous a dit de le faire : contrats, vérifications et emplacements de code prêts à l’emploi pour les équipes souhaitant utiliser ce modèle.