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.
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 comoread-cypheren 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_USERNAMEyNEO4J_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 Alloweden 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
initializey asegúrese de que estén instalados APOC y GDS.
get-schema falla: APOC no está instalado. Agréguelo a NEO4J_PLUGINS.NEO4J_USERNAME o NEO4J_PASSWORD se configuraron en modo HTTP. Elimínelos ambos.mcp.json aún contiene la configuración de stdio. Cambie a la configuración de http.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
- Seguridad de un servidor Spring AI MCP con OAuth 2.0 y alcances por herramienta — Crea un servidor de autorización OAuth y convierte un servidor Spring AI MCP en un servidor de recursos, pruébalo en MCP Inspector y luego restringe herramientas individuales mediante alcances.
- Notas prácticas: Microsoft construyó el servidor MCP de Playwright. Luego te dijo que — Guía paso a paso de las Notas prácticas: Microsoft construyó el servidor MCP de Playwright. Luego te dijo que: contratos, verificaciones y espacios de código listos para usar para equipos que implementan este patrón.