Neo4j MCP — Casos de uso, Instalar & Demo en vivo

Por qué usarlo

Características clave

Ejecuta consultas Cypher arbitrarias de lectura o escritura
Introspección de esquema: etiquetas, tipos de relaciones, claves de propiedad, restricciones, índices
Funciona con Neo4j Community, Enterprise, AuraDB y Neo4j Desktop
Servidor Aura-admin separado para aprovisionar instancias en Neo4j Aura
Superficie de herramientas pequeña y enfocada — sin magia; controlas cada Cypher

Demo en vivo

Cómo se ve en la práctica

neo4j.replay ▶ listo

0/0

Instalar

Elige tu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "neo4j": {
      "command": "uvx",
      "args": [
        "mcp-neo4j-cypher"
      ]
    }
  }
}

Abre Claude Desktop → Settings → Developer → Edit Config. Reinicia después de guardar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "neo4j": {
      "command": "uvx",
      "args": [
        "mcp-neo4j-cypher"
      ]
    }
  }
}

Cursor usa el mismo esquema mcpServers que Claude Desktop. La configuración del proyecto prevalece sobre la global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "neo4j": {
      "command": "uvx",
      "args": [
        "mcp-neo4j-cypher"
      ]
    }
  }
}

Haz clic en el icono MCP Servers de la barra lateral de Cline y luego en "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "neo4j": {
      "command": "uvx",
      "args": [
        "mcp-neo4j-cypher"
      ]
    }
  }
}

Mismo formato que Claude Desktop. Reinicia Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "neo4j",
      "command": "uvx",
      "args": [
        "mcp-neo4j-cypher"
      ]
    }
  ]
}

Continue usa un array de objetos de servidor en lugar de un mapa.

~/.config/zed/settings.json

{
  "context_servers": {
    "neo4j": {
      "command": {
        "path": "uvx",
        "args": [
          "mcp-neo4j-cypher"
        ]
      }
    }
  }
}

Añádelo a context_servers. Zed recarga en caliente al guardar.

claude mcp add neo4j -- uvx mcp-neo4j-cypher

Un solo comando. Verifica con claude mcp list. Quita con claude mcp remove.

Casos de uso

Usos del mundo real: Neo4j

Explora un esquema de grafo desconocido en 5 minutos

👤 Ingenieros / analistas que heredan una BD Neo4j ⏱ ~15 min beginner

Cuándo usarlo: Te entregaron una BD de grafo sin documentación. Necesitas un modelo mental antes de poder escribir consultas útiles.

Requisitos previos

Neo4j Bolt URL + user/password — NEO4J_URI=bolt://host:7687, NEO4J_USERNAME, NEO4J_PASSWORD
Usuario de solo lectura recomendado para exploración — CREATE USER claude SET PASSWORD '...' SET ROLES reader

Flujo

Obtén una visión general del esquema

Llama a get_neo4j_schema. Resume las etiquetas de nodos, tipos de relaciones y los patrones (label)-[rel]->(label) más comunes.✓ Copiado

→ Resumen de esquema con triples de ejemplo
Muestrea nodos representativos

Para las 3 etiquetas más comunes, ejecuta MATCH (n:Label) RETURN n LIMIT 3 cada una. Describe qué parece representar cada etiqueta.✓ Copiado

→ Descripciones semánticas de etiquetas
Dibuja el modelo ER probable

Basándote en el esquema y las muestras, describe en prosa la historia de 'entidades' de este grafo. ¿Cuál es el objeto principal, qué se conecta a él, qué es periférico?✓ Copiado

→ Descripción clara del modelo de dominio

Resultado: Un modelo de dominio de una página que puedas validar con los autores originales.

Errores comunes

Muestrear grafos pequeños da patrones engañosos — También ejecuta MATCH (n)-[r]->() RETURN type(r), count(*) para ver cuáles rels dominan

Combinar con: filesystem

Escribe consultas de grafo para detectar anillos de fraude

👤 Analistas de riesgo / fraude ⏱ ~40 min advanced

Cuándo usarlo: Sospechas de anillos de fraude de dispositivo compartido o dirección compartida entre cuentas.

Requisitos previos

Grafo con nodos User, Device, Address, Payment y relaciones :USED, :LIVES_AT, :PAID — Forma de grafo de fraude típica

Flujo

Encuentra dispositivos compartidos

Encuentra dispositivos utilizados por 3 o más usuarios diferentes en los últimos 30 días. Devuelve device_id + lista de user_ids + ts de último uso por par.✓ Copiado

→ Candidatos de anillo
Puntuación por tamaño de componente conectado

Usando GDS o Cypher puro, calcula componentes conectados sobre User-(:USED)-Device-(:USED)-User. Devuelve los 10 componentes principales por tamaño.✓ Copiado

→ Grupos sospechosos
Produce una lista accionable

Para cada grupo principal, lista usuarios distintos, volumen total de transacciones y actividad más antigua/más reciente. Marca los grupos > $10k para revisión de alta prioridad.✓ Copiado

→ Entradas de cola de analista

Resultado: Una cola de revisión de fraude priorizada con el Cypher exacto preservado.

Errores comunes

Los recorridos ingenuos explotan en hubs (dispositivo de wifi público compartido con 10k usuarios) — Limita la profundidad y filtra los nodos hub por grado antes de recorrer

Combinar con: postgres

Prototipa una consulta de recomendación de contenido

👤 Ingenieros de producto construyendo 'usuarios que también gustaron' ⏱ ~30 min intermediate

Cuándo usarlo: Tienes User-LIKED->Item y quieres recomendar elementos de usuarios similares.

Flujo

Elige un usuario y encuentra vecinos

Para el usuario <id>, encuentra 20 usuarios que comparten la mayoría de elementos LIKED. Devuelve user_id y recuento de superposición.✓ Copiado

→ Usuarios similares clasificados
Recomienda elementos que esos usuarios gustaron

Para esos 20 usuarios similares principales, lista elementos que gustaron que <id> NO ha gustado. Clasifica por número de usuarios similares que lo gustaron.✓ Copiado

→ Recomendaciones de Top-N
Conviértelo en una consulta reutilizable

Parametriza como Cypher invocable con $user_id; agrega índices necesarios para velocidad.✓ Copiado

→ Consulta lista para producción + declaraciones CREATE INDEX

Resultado: Una consulta de filtrado colaborativo que funciona, lo suficientemente rápida para servir en línea.

Errores comunes

Olvidar un índice en :User(id) hace que las consultas de inicio sean lineales — Ejecuta CREATE INDEX FOR (u:User) ON (u.id) y EXPLAIN para confirmar que se usa

Carga datos relacionales en Neo4j desde una tabla de ensayo

👤 Ingenieros de datos migrando de SQL a grafo ⏱ ~40 min advanced

Cuándo usarlo: Tienes usuarios + follows en Postgres y quieres una representación de grafo.

Requisitos previos

Usuario Neo4j escribible — Rol con CREATE en la BD de destino

Flujo

Planifica el mapeo de nodos/bordes

Dados los tables users(id, name) y follows(from_id, to_id), propón el modelo Neo4j. ¿Etiqueta(s)? ¿Dirección de relación?✓ Copiado

→ (:User {id,name})-[:FOLLOWS]->(:User)
Crea restricciones primero

Genera CREATE CONSTRAINT FOR (u:User) REQUIRE u.id IS UNIQUE. Ejecútalo.✓ Copiado

→ Restricción creada
Carga masiva con MERGE

A partir de las filas de usuario proporcionadas, ejecuta UNWIND $rows AS r MERGE (:User {id:r.id}) ... luego follows con MERGE (a)-[:FOLLOWS]->(b). Lotes de 10k a la vez.✓ Copiado

→ Todas las filas cargadas idempotentemente

Resultado: Un ETL re-ejecutable que carga tus datos relacionales en una forma de grafo.

Errores comunes

CREATE en lugar de MERGE crea nodos duplicados en re-ejecución — Siempre MERGE para upserts, y requiere una restricción de singularidad antes de MERGE masivo para velocidad

Combinar con: postgres

Responde preguntas en lenguaje natural sobre un grafo de conocimiento

👤 Equipos internos con un KG de dominio ⏱ ~25 min intermediate

Cuándo usarlo: Construiste una pequeña ontología (productos, características, clientes) y quieres que Claude responda 'qué clientes usan la característica X' sin aprender Cypher.

Flujo

Ancla Claude en el esquema

Aquí está el esquema [pega la salida de get_neo4j_schema]. De ahora en adelante, traduce mis preguntas a Cypher antes de ejecutarlas.✓ Copiado

→ Claude repite la comprensión del esquema
Haz una pregunta, obtén Cypher + respuesta

¿Qué clientes usan la característica 'export-csv' en el último trimestre?✓ Copiado

→ Cypher mostrado + tabla de resultados
Refina cuando Cypher es incorrecto

Ese Cypher perdió la relación :USED a Session. Corrígelo para pasar a través de sesiones.✓ Copiado

→ Cypher corregido re-ejecutado

Resultado: Una interfaz NL-to-Cypher ligera para colegas no técnicos.

Errores comunes

Claude inventa etiquetas que no existen — Fíjalo: 'solo usa etiquetas/rels del esquema proporcionado; de lo contrario, di desconocido'

Combinaciones

Combínalo con otros MCPs para multiplicar por 10

neo4j + postgres

Sincroniza datos relacionales a una representación de grafo

Extrae usuarios + follows de Postgres, luego MERGE en Neo4j como (:User)-[:FOLLOWS]->(:User).✓ Copiado

neo4j + qdrant

RAG mejorado por grafo: usa Qdrant para recuperación semántica, Neo4j para relaciones precisas

Qdrant encuentra docs similares a la pregunta; luego recorre Neo4j desde entidades coincidentes para extraer hechos estructurados para la respuesta.✓ Copiado

neo4j + filesystem

Exporta un informe generado por Cypher como CSV/Markdown

Ejecuta el Cypher de anillo de fraude, exporta los 50 grupos principales como /reports/fraud-<date>.csv.✓ Copiado

Herramientas

Lo que expone este MCP

Herramienta	Entradas	Cuándo llamar	Coste
get_neo4j_schema		Siempre primero en una nueva sesión	free
read_neo4j_cypher	query: str, params?: object	Cualquier MATCH / RETURN — solo lectura	free
write_neo4j_cypher	query: str, params?: object	CREATE/MERGE/SET/DELETE — mutaciones	free

Coste y límites

Lo que cuesta ejecutarlo

Cuota de API: Limitado por tu instancia Neo4j. Aura Free: 200k nodos/400k rels.
Tokens por llamada: Esquema: ~500 tokens. Resultados de consulta: depende de filas+propiedades.
Monetario: Gratuito para Community / auto-hospedado. Capa Aura Free existe. Aura pagado desde ~$65/mes.
Consejo: Siempre EXPLAIN primero en grafos grandes; un índice faltante en una etiqueta de inicio convierte una consulta de 5ms en un escaneo de 5min.

Seguridad

Permisos, secretos, alcance

Ámbitos mínimos: rol reader para exploración de solo lectura

Almacenamiento de credenciales: NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD en env

Salida de datos: Conexión Bolt directa a tu Neo4j (auto-hospedado o Aura)

No conceder nunca: rol admin acceso PUBLIC de escritura

DROP DATABASE y CREATE CONSTRAINT requieren roles elevados — mantenlos en un perfil de conexión solo de administrador separado.
Ejecuta el MCP con una cuenta de rol reader para cualquier sesión que no necesite explícitamente escribir.

Resolución de problemas

Errores comunes y soluciones

ServiceUnavailable: Connection refused

Neo4j no está ejecutándose o puerto Bolt incorrecto (predeterminado 7687). Comprueba con cypher-shell -a bolt://host:7687.

Verificar: nc -zv host 7687

Neo.ClientError.Security.Unauthorized

Usuario/contraseña incorrecto. Restablece a través de CALL dbms.security.changePassword('new') desde una sesión de administrador.

Neo.ClientError.Statement.SyntaxError

El Cypher de Claude tiene un error tipográfico — pega el error exacto, pide una consulta corregida.

Writes fail: Write operation not allowed in read-only mode

Estás conectado con un rol reader; cambia a un usuario con WRITE o usa una conexión de escritor separada.

Alternativas

Neo4j vs otros

Alternativa	Cuándo usarla	Contrapartida
Memgraph MCP	Necesitas análisis de grafo en tiempo real; Memgraph es compatible con Cypher	Ecosistema más pequeño, menos opciones hospedadas
ArangoDB MCP	Quieres multi-modelo (grafo + documento + KV)	AQL en lugar de Cypher; curva de aprendizaje
Postgres + Apache AGE	Eres principalmente relacional con algunas necesidades de grafo	Rendimiento de grafo peor que Neo4j nativo en recorridos grandes

Más

Recursos

📖 Lee el README oficial en GitHub

🐙 Ver issues abiertas

🔍 Ver todos los 400+ servidores MCP y Skills