Inicio / Artículos

Ejecuta el servidor MCP de Neo4j en tu propia máquina con Docker y VS Code

Autohospeda Neo4j y su servidor MCP oficial con Docker Compose, protege la conexión con autenticación básica a través de HTTP, conecta VS Code en modo Agente y consulta un grafo de ejemplo.

Editor: REACTAPP.TOP8 min de lectura1743 palabras

Fuentes: Run the Neo4j MCP Server Locally with Docker (No Codespaces Needed)

El servidor MCP oficial de Neo4j es un programa pequeño, y toda la infraestructura puede ejecutarse en una laptop con Docker en aproximadamente media hora. Esto es importante para quienes siguen el curso GraphAcademy sobre desarrollo con herramientas MCP de Neo4j, ya que el curso asume el uso de GitHub Codespaces, y estos tienen un límite mensual gratuito que eventualmente se agota. Al alojarlo uno mismo se elimina ese límite y no cuesta nada. Los pasos a continuación se ejecutaron de principio a fin, y también muestran cómo se integran las diferentes partes de MCP.

Qué se crea

VS Code (host)  ──HTTP /mcp + auth──►  neo4j-mcp (server)  ──Bolt──►  Neo4j (database)

La configuración está formada por tres partes separadas, y comprender claramente esta división resuelve la mayor parte de las dudas.

  • Host: el cliente MCP, como por ejemplo VS Code, Claude Desktop o Cursor. Este se encarga del protocolo MCP y no tiene conocimiento de la existencia de Neo4j.
  • Servidor MCP: el puente neo4j-mcp, que convierte las llamadas de herramientas MCP como read-cypher en consultas reales de Bolt.
  • Banco de datos: Neo4j en sí.

Un malentendido frecuente es pensar que alguna “base de datos MCP” remota se encuentra en la nube. Eso no es cierto. El servidor MCP es un programa que se ejecuta localmente y se conecta hacia el banco de datos al que esté dirigido.

Requisitos previos

Debe estar instalado y en ejecución Docker Desktop, lo cual se puede confirmar con docker --version. Se necesita VS Code con soporte MCP, además de una terminal. No es necesario instalar Python ni Neo4j, ya que Docker lo cubre todo.

Paso 1: Escribir la pila Docker

Cree una carpeta de proyecto y coloque en ella un archivo docker-compose.yml. Este archivo define dos servicios. El primero es la base de datos:

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 segundo lugar está el servidor MCP, creado directamente desde el repositorio oficial en una etiqueta fija:

  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:

Hay dos detalles aquí que merecen atención.

  • Transporte HTTP en lugar de stdio. El curso inicia el servidor en modo stdio, donde el sistema lo lanza como un proceso hijo. Esta configuración lo ejecuta como un servicio HTTP independiente, lo cual está más cerca de un despliegue real y permite que cualquier cliente se conecte mediante una URL.
  • Por qué esos valores. El contenedor no tiene privilegios de root, por lo que es imposible vincular un puerto con privilegios inferior a 1024. Por esa razón, el puerto 8000 sustituye al 80. En modo HTTP, el servidor también rechaza por diseño las variables de entorno NEO4J_USERNAME y NEO4J_PASSWORD. Las credenciales se envían con cada solicitud a través de autenticación básica HTTP, lo cual coincide con el modelo de autenticación en producción, por lo que esas variables no se utilizan.

Paso 2: Iníciarlo

docker compose up -d --build

La primera ejecución descarga la imagen de Neo4j, compila el servidor MCP de Go y descarga los complementos APOC y GDS. Después de aproximadamente un minuto, verifique que ambos contenedores estén en funcionamiento:

docker compose ps

Espera a que neo4j indique (healthy).

Paso 3: Verificar el servidor

El endpoint MCP se encuentra en http://localhost:8000/mcp. Al abrirlo en un navegador se muestra Method Not Allowed: only POST is supported. En realidad, eso es alentador, ya que significa que el servidor está activo y el navegador simplemente envió una solicitud GET.

Utiliza curl para realizar una prueba adecuada. Comienza confirmando que se aplica autenticación:

curl -i -X POST http://localhost:8000/mcp        # expect 401 Unauthorized

A continuación, enumere las herramientas mientras se autentica con las credenciales de la base de datos:

curl -s -u neo4j:password123 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
  http://localhost:8000/mcp

La respuesta debe mencionar get-schema, read-cypher y write-cypher.

¿Por qué solo aparecen tres herramientas?

El curso describe cuatro herramientas, y la que falta es list-gds-procedures. No hay ningún problema. Esa herramienta se registra de forma diferida durante el proceso de establecimiento de conexión MCP initialize, y solo cuando está instalado Graph Data Science. Una solicitud simple de tools/list omite ese proceso, por lo que la cuarta herramienta nunca aparece. Envíe primero initialize y luego vuelva a listar:

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

Ahora aparecen las cuatro herramientas. Los clientes reales como VS Code ejecutan initialize por sí mismos, por lo que esta peculiaridad solo afecta a las llamadas directas con curl.

Paso 4: Conectar VS Code

Cree .vscode/mcp.json en el proyecto:

{
    "servers": {
        "neo4j": {
            "type": "http",
            "url": "http://localhost:8000/mcp",
            "headers": {
                "Authorization": "Basic bmVvNGo6cGFzc3dvcmQxMjM="
            }
        }
    }
}

El valor de Authorization es simplemente la codificación base64 de neo4j:password123. Después de cambiar la contraseña, regénrela con:

printf 'neo4j:yourpassword' | base64

El error más común es reutilizar la configuración stdio del curso ("type": "stdio", "command": "neo4j-mcp") con esta configuración de Docker. Eso le indica a VS Code que inicie un binario local que no existe. Un servidor contenerizado necesita la configuración http mostrada anteriormente.

En VS Code, abra la paleta de comandos con Cmd/Ctrl + Shift + P, ejecute MCP: List Servers, elija neo4j y seleccione Start Server. A continuación, cambie Chat a modo Agent (Cmd/Ctrl + Shift + I) y solicite una lista de las herramientas MCP disponibles con sus IDs y descripciones. Se devuelven cuatro herramientas.

Paso 5: Utilizarlo

La base de datos local comienza vacía, por lo que un segundo contenedor MCP desechable puede apuntar a la base de datos de demostración pública de películas de Neo4j, la misma que utiliza el curso, en un puerto diferente. La pila principal permanece sin cambios:

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

El nombre de la imagen es el que genera docker compose. Ejecuta docker images para verlo; esperarás algo como yourfolder-neo4j-mcp.

Para leer el esquema y ver qué relaciones tiene un User, llama a 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 respuesta es RATED, lo que significa (:User)-[:RATED]->(:Movie).

Para generar una consulta para la película con la calificación más alta, incluya una condición de no nulo, ya que no todas las películas tienen calificación:

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

Cuando termine la demostración, detenga el contenedor:

docker stop mcp-movies

Paso 6: Una pequeña aplicación en la parte superior

El curso finaliza con que los estudiantes creen una herramienta de línea de comandos en Python que muestra las cinco películas más destacadas de un género determinado. Esta versión simplificada pasa el género como parámetro de consulta, nunca mediante concatenación de cadenas, y filtra las calificaciones nulas:

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()

Ejecútelo contra la base de datos de demostración:

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

Qué se logró

En aproximadamente media hora, toda la pila MCP de Neo4j funciona localmente sin necesidad de Codespaces ni facturas de nube:

  • Neo4j con APOC y GDS, además del servidor oficial neo4j-mcp, ambos en Docker
  • El servidor MCP como servicio HTTP autenticado
  • VS Code conectado en modo Agent
  • Consultas reales a través de las herramientas MCP y una pequeña aplicación en Python

Por qué el auto-hospedaje enseña más

Podría parecer una forma de eludir cuotas, pero ejecutar el servidor personalmente muestra algo mucho más útil. MCP se está convirtiendo en la vía estándar para que los agentes de IA accedan a sistemas reales: bases de datos, APIs y herramientas internas. Las preguntas de ingeniería interesantes surgen precisamente en este escenario. ¿Cómo se transporta el servidor? ¿Cómo se autentican las solicitudes? ¿Qué evita que un agente ejecute una consulta destructiva?

Operar el servidor a través de HTTP, con autenticación por solicitud y un modo solo de lectura, saca a la luz esas dudas, mientras que un entorno aislado ya preparado las oculta. Dado que cada vez más los agentes acceden a datos de producción reales, es más importante ejecutar un servidor MCP como un servicio controlado y observable que confiar en una caja negra alojada por otra persona. El mismo enfoque se aplica a una implementación real detrás de una pasarela con TLS y un gestor de secretos.

Resolución de problemas

  • Method Not Allowed en el navegador: la solicitud fue de tipo GET y el endpoint solo acepta POST. Utilice curl o un cliente MCP.
  • 401 Unauthorized: falta o está incorrecta la autenticación básica. Use el nombre de usuario y la contraseña de la base de datos.
  • Solo se muestran tres herramientas: envíe primero initialize y asegúrese de que estén instalados APOC y GDS.
  • get-schema falla: APOC no está instalado. Agréguelo a NEO4J_PLUGINS.
  • El servidor se niega a iniciar y muestra un error relacionado con las credenciales: NEO4J_USERNAME o NEO4J_PASSWORD se configuraron en modo HTTP. Elimínelos ambos.
  • VS Code indica que el servidor “requiere interacción para iniciar”: mcp.json aún contiene la configuración de stdio. Cambie a la configuración de http.
  • Se deniega el permiso al vincular el puerto: mantenga NEO4J_MCP_HTTP_PORT por encima de 1024, ya que el contenedor no es root.
  • Leer más

    La documentación del servidor MCP de Neo4j y la especificación oficial de MCP detallan estos aspectos.

    Temas relacionados

  • Conectar repositorios privados de GitHub a Claude Desktop con un token y Docker — Crea un token clásico de GitHub con alcances seguros, agrega el servidor MCP de GitHub a Claude Desktop a través de Docker, pruébalo y úsalo para la revisión de PR, la triage y los registros de cambios.