Accueil / Articles

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.

Éditeur : REACTAPP.TOP8 min de lecture1743 mots

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 que read-cypher en 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_USERNAME et NEO4J_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 Allowed dans 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.
  • Le serveur refuse de démarrer et signale un problème avec les identifiants : NEO4J_USERNAME ou NEO4J_PASSWORD a été défini en mode HTTP. Supprimez-les tous les deux.
  • VS Code indique que le serveur « nécessite une interaction pour démarrer » : mcp.json contient encore la configuration stdio. Utilisez plutôt celle en mode http.
  • Droit refusé lors du bindement du port : maintenez 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

  • Connecter des repos Private GitHub à Claude Desktop avec un token et Docker — Créer un token GitHub classique doté de scopes sécurisés, ajouter le serveur GitHub MCP à Claude Desktop via Docker, le tester, et l’utiliser pour l’examen des PR, le tri des tâches et les journaux de modifications.