Neo4j MCP

Un servidor del Protocolo de Contexto de Modelos (MCP) que permite a Claude (y a otros clientes MCP) consultar y modificar bases de datos de grafos Neo4j. Se distribuye tanto como un servidor MCP independiente como un plugin de Claude Code que puedes instalar una vez y reutilizar en cualquier proyecto.

Cada proyecto proporciona sus propias credenciales de Neo4j a través de un archivo .env local, por lo que el mismo plugin puede apuntar a diferentes bases de datos dependiendo de la carpeta en la que se abra Claude Code.

Características

• Una herramienta consolidada cypher_query con modo explícito de read / write.

• Inspección de esquema: etiquetas, tipos de relación y claves de propiedad.

• Serialización completa de resultados: conserva element_id de nodos/relaciones, etiquetas, tipos y valores temporales/espaciales de Neo4j.

• Límite de tamaño de resultados con indicador de truncamiento, para que un MATCH (n) descontrolado no sature la respuesta.

• Credenciales por proyecto a través de .env (cargado por python-dotenv desde el directorio de trabajo).

• Funciona con stdio (Claude Code, Claude Desktop, Cursor) y SSE.

Related MCP server: neo4j-server-remote

Requisitos previos

• Python 3.10+

• Una base de datos Neo4j accesible (local, Docker o Aura)

• pip (o uv, pipx)

Instalar el paquete de Python

El plugin invoca un script de consola llamado neo4j-mcp-server, por lo que el paquete debe estar primero en tu PATH.

git clone https://github.com/your-repo/neo4j-mcp.git
cd neo4j-mcp
pip install -e .

Verifica que se haya instalado:

which neo4j-mcp-server
neo4j-mcp-server --help

Consejo: si usas pipx, pipx install -e . mantiene el servidor aislado de tu Python global.

Úsalo como plugin de Claude Code

El repositorio incluye un manifiesto de plugin en .claude-plugin/plugin.json. Una vez instalado a nivel de usuario, el servidor MCP neo4j está disponible en cada sesión de Claude Code, en cualquier proyecto.

1. Instalar el plugin

Desde dentro de Claude Code:

/plugin install /absolute/path/to/neo4j-mcp

Eso registra el manifiesto globalmente. (También puedes añadirlo a través de un marketplace si publicas uno; consulta la documentación de plugins de Claude Code).

2. Coloca un .env en cualquier proyecto que deba comunicarse con Neo4j

El servidor MCP hereda el directorio de trabajo de Claude Code, por lo que python-dotenv detecta cualquier .env que resida en la raíz de ese proyecto. Diferentes carpetas → diferentes bases de datos, sin necesidad de reconfigurar el plugin.

# my-project/.env
NEO4J_HOST=localhost
NEO4J_PORT=7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-secret
NEO4J_DATABASE=neo4j

Para Aura / conexiones cifradas:

NEO4J_HOST=xxx.databases.neo4j.io
NEO4J_PORT=7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-aura-password
NEO4J_URI_SCHEME=neo4j+s
NEO4J_ENCRYPTED=true

Para una instancia local sin autenticación, deja NEO4J_USERNAME y NEO4J_PASSWORD en blanco.

No subas el .env al control de versiones. Añádelo al .gitignore en cada proyecto.

3. Úsalo desde Claude Code

Abre el proyecto y luego pídele a Claude cosas como:

• "¿Qué etiquetas y tipos de relación existen en este grafo?"

• "Encuentra los 10 nodos Person más conectados."

• "Crea un nodo Movie titulado Inception lanzado en 2010."

Claude llamará a las herramientas cypher_query, get_database_schema y test_database_connection según sea necesario.

Úsalo sin Claude Code

El mismo paquete funciona como un servidor MCP estándar para cualquier cliente compatible con MCP.

Claude Desktop / Cursor

Añádelo a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o a tu configuración de MCP de Cursor:

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

Establece las credenciales colocando un .env junto a donde el cliente inicia el proceso, o exportando variables NEO4J_* en el bloque de entorno.

Transporte SSE (clientes web)

neo4j-mcp-server --transport sse --host 0.0.0.0 --port 3000

CLI independiente

Se incluye un pequeño cliente para pruebas rápidas:

neo4j-mcp-client --test
neo4j-mcp-client --schema
neo4j-mcp-client --query "MATCH (n) RETURN count(n) AS nodes"
neo4j-mcp-client --write --query "CREATE (p:Person {name: 'Alice'}) RETURN p"

Referencia de configuración

Todos los ajustes se leen de variables de entorno (o de un archivo .env en el directorio de trabajo).

Herramientas expuestas por el servidor MCP

Recursos: neo4j://schema, neo4j://connection. Prompt: cypher_query_help.

Desarrollo

pip install -e ".[dev]"
pytest                    # 21 unit tests, no live database needed
ruff check src/ tests/
mypy src/neo4j_mcp/

Solución de problemas

• Neo4j authentication failed — error de coincidencia de usuario/contraseña. Para bases de datos sin autenticación, deja ambos en blanco (no los establezcas como neo4j/neo4j).

• Neo4j service unavailable — la base de datos está caída o NEO4J_HOST / NEO4J_PORT son incorrectos. Prueba cypher-shell -a bolt://$NEO4J_HOST:$NEO4J_PORT para confirmar.

• El plugin no encuentra neo4j-mcp-server — el script de consola no está en el PATH que hereda Claude Code. Instálalo con pipx o asegúrate de que tu archivo rc de shell exporte el PATH correcto para aplicaciones GUI. En macOS, las aplicaciones GUI no leen ~/.zshrc; usa launchctl setenv PATH ... o instálalo en /usr/local/bin.

• truncated: true en una lectura — aumenta el limit en la llamada, o establece un NEO4J_DEFAULT_RESULT_LIMIT más alto en .env.

Licencia MIT.