Neo4j

Neo4j MCP

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

Cada proyecto proporciona sus propias credenciales de Neo4j mediante un archivo local .env, de modo que el mismo plugin puede apuntar a diferentes bases de datos según la carpeta en la que se abra Claude Code.

---

Características

• Una herramienta consolidada cypher_query con modo explícito read / write.
• Introspección de esquema: etiquetas, tipos de relaciones y claves de propiedades.
• Serialización completa de resultados: conserva element_id de nodos/relaciones, etiquetas, tipos y valores temporales/espaciales de Neo4j.
• Protección de tamaño de resultados con indicador de truncamiento, para que un MATCH (n) descontrolado no haga explotar la respuesta.
• Credenciales por proyecto mediante .env (cargado por python-dotenv desde el directorio de trabajo).
• Funciona con stdio (Claude Code, Claude Desktop, Cursor) y SSE.

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 en tu PATH primero.

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.

Usarlo 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 todas las sesiones 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 mediante un marketplace si publicas uno; consulta la documentación de plugins de Claude Code).

2. Coloca un .env en cualquier proyecto que deba conectarse a Neo4j

El servidor MCP hereda el directorio de trabajo de Claude Code, por lo que python-dotenv recoge el .env que se encuentre en la raíz de ese proyecto. Carpetas diferentes → bases de datos diferentes, 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 hagas commit de .env. Añádelo a .gitignore en cada proyecto.

3. Usarlo desde Claude Code

Abre el proyecto y luego pide a Claude cosas como:

• "¿Qué etiquetas y tipos de relaciones existen en este grafo?"
• "Encuentra los 10 nodos Person más conectados."
• "Crea un nodo Movie titulado Inception estrenado en 2010."

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

Usarlo sin Claude Code

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

Claude Desktop / Cursor

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

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

Establece las credenciales colocando un .env junto a donde el cliente inicie 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 puntuales:

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

Variable	Valor predeterminado	Descripción
NEO4J_HOST	localhost	Host de Bolt
NEO4J_PORT	7687	Puerto de Bolt
NEO4J_HTTP_PORT	7474	Puerto de navegador/HTTP (informativo)
NEO4J_USERNAME	(vacío)	Déjalo en blanco para bases de datos sin autenticación
NEO4J_PASSWORD	(vacío)
NEO4J_DATABASE	neo4j	Base de datos predeterminada
NEO4J_URI_SCHEME	bolt	Uno de bolt, bolt+s, neo4j, neo4j+s
NEO4J_ENCRYPTED	false	Establece true para Aura / TLS
NEO4J_DEFAULT_RESULT_LIMIT	100	Límite de filas para consultas de lectura cuando no se proporciona
NEO4J_MAX_CONNECTION_POOL_SIZE	100	Tamaño del pool del controlador
NEO4J_CONNECTION_TIMEOUT	30.0	Segundos

Herramientas expuestas por el servidor MCP

Herramienta	Propósito
cypher_query(query, mode="read"|"write", parameters?, database?, limit?)	Ejecuta cualquier consulta Cypher. Usa mode="write" para CREATE / MERGE / SET / DELETE, incluso si también RETURN filas. Devuelve {records, record_count, truncated, stats}.
get_database_schema(database?)	Devuelve etiquetas, tipos de relaciones y claves de propiedades.
test_database_connection()	Verifica la conectividad, devuelve la cadena del agente del servidor y la versión del protocolo Bolt.

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 — discrepancia de usuario/contraseña. Para bases de datos sin autenticación, deja ambos en blanco (no los establezcas en 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. Instala con pipx o asegúrate de que tu archivo rc del shell exporte el PATH correcto para aplicaciones GUI. En macOS, las aplicaciones GUI no leen ~/.zshrc; usa launchctl setenv PATH ... o instala en /usr/local/bin.
• truncated: true en una lectura — aumenta limit en la llamada, o establece NEO4J_DEFAULT_RESULT_LIMIT más alto en .env.

---

Licencia MIT.