Neo4j MCP Server

Un servicio de consulta de solo lectura para bases de datos gráficas Neo4j.

GitHubPrueba este MCPPatrocinado

Documentación

Documentación de uso de Neo4j MCP Server

Introducción

Neo4j MCP Server es un servicio de consulta de solo lectura para bases de datos Neo4j, construido sobre Spring AI y el Protocolo de Contexto de Modelo (MCP). Proporciona a los asistentes de IA la capacidad de acceder de forma segura a la base de datos de grafos Neo4j.

Inicio rápido

1. Requisitos del entorno

  • Java 21+
  • Maven 3.6+
  • Base de datos Neo4j (local o remota)

2. Configurar la conexión a la base de datos

Edite src/main/resources/application.properties:

# Neo4j 数据库连接配置
neo4j.uri=bolt://localhost:7687
neo4j.username=neo4j
neo4j.password=your_password
neo4j.database=neo4j

3. Iniciar el servidor

# 编译和运行
./mvnw spring-boot:run

# 或者打包后运行（跳过测试）
./mvnw clean package -DskipTests
java -jar target/neo4jmcp-0.0.1-SNAPSHOT.jar

Después de un inicio exitoso, verá:

INFO o.s.a.m.s.a.McpServerAutoConfiguration : Registered tools: 10
INFO com.hy.neo4jmcp.Neo4jmcpApplication    : Started Neo4jmcpApplication

Herramientas disponibles

Herramientas de consulta principales

1. executeCypher

Ejecuta consultas Cypher de solo lectura

// 示例调用
executeCypher("MATCH (n:Person) RETURN n.name LIMIT 10", {})

2. getDatabaseInfo

Obtiene información completa de la base de datos (versión, estadísticas, esquema, etc.)

3. getNodeLabels

Obtiene la lista de todas las etiquetas de nodos

4. getRelationshipTypes

Obtiene la lista de todos los tipos de relaciones

5. getPropertyKeys

Obtiene la lista de todas las claves de propiedades

Herramientas de consulta de esquema

6. getSchemaInfo

Obtiene información sobre restricciones e índices de la base de datos

7. findNodesByLabel

Busca nodos por etiqueta, con soporte para filtrado por propiedades

// 示例：查找特定属性的Person节点
findNodesByLabel("Person", {"age": 25}, 50)

Herramientas de recorrido de grafos

8. getRelationshipsBetweenNodes

Obtiene las relaciones entre dos nodos

// 示例：查找节点123和456之间的KNOWS关系
getRelationshipsBetweenNodes(123, 456, "KNOWS")

9. getNodeNeighborhood

Obtiene el vecindario de un nodo (nodos conectados)

// 示例：获取节点123的2层邻居，最多返回100个
getNodeNeighborhood(123, 2, 100)

10. searchNodesByText

Busca texto en las propiedades de los nodos

// 示例：在Person节点中搜索包含"John"的属性
searchNodesByText("John", "Person", 50)

Conexión del cliente MCP

Conexión en modo STDIO

Este servidor habilita el modo de transporte STDIO de forma predeterminada y puede ser conectado directamente por clientes MCP:

{
  "mcpServers": {
    "neo4j": {
      "command": "java",
      "args": ["-jar", "/path/to/neo4jmcp-0.0.1-SNAPSHOT.jar"]
    }
  }
}

Integración con Claude Desktop

Agregue lo siguiente al archivo de configuración de Claude Desktop:

{
  "mcpServers": {
    "neo4j-server": {
      "command": "java",
      "args": [
        "-jar", 
        "/Users/carl/IdeaProjects/neo4jmcp/target/neo4jmcp-0.0.1-SNAPSHOT.jar"
      ]
    }
  }
}

Características de seguridad

Protección de solo lectura

  • ✅ Solo se permiten operaciones de lectura como MATCH, RETURN, WITH, OPTIONAL MATCH, UNWIND
  • ❌ Se prohíben operaciones de escritura como CREATE, MERGE, DELETE, SET, DROP
  • ✅ Se permiten algunos comandos SHOW (CONSTRAINTS, INDEXES, PROCEDURES, FUNCTIONS)

Límites de consulta

  • Número máximo de registros devueltos por consulta: 1000
  • Tiempo de espera de consulta: 30 segundos
  • Número máximo de conexiones en el grupo de conexiones: 50

Parámetros de configuración

Configuración del servidor MCP

spring.ai.mcp.server.enabled=true
spring.ai.mcp.server.name=neo4j-mcp-server
spring.ai.mcp.server.type=ASYNC
spring.ai.mcp.server.stdio=true

Configuración de conexión Neo4j

neo4j.uri=bolt://localhost:7687
neo4j.username=neo4j
neo4j.password=your_password
neo4j.database=neo4j
neo4j.max-connection-pool-size=50
neo4j.connection-acquisition-timeout=60s
neo4j.connection-timeout=5s
neo4j.max-transaction-retry-time=15s
neo4j.max-query-execution-time=30s
neo4j.max-result-records=1000

Solución de problemas

Problemas comunes

  1. Error de conexión

    • Verifique que el servicio Neo4j esté iniciado
    • Valide los parámetros de conexión (URI, nombre de usuario, contraseña)
    • Confirme la configuración del firewall

  2. Herramientas no registradas

    • Revise la información de "Registered tools" en los registros de inicio
    • Confirme que la configuración automática de Spring AI funcione correctamente

  3. Consulta rechazada

    • Confirme que la consulta sea una operación de solo lectura
    • Verifique que la sintaxis de Cypher sea correcta

Ajuste del nivel de registro

logging.level.com.hy.neo4jmcp=DEBUG
logging.level.org.springframework.ai.mcp=DEBUG

Ejemplos de uso

Exploración básica de grafos

-- 查看数据库概览
MATCH (n) RETURN labels(n), count(n)

-- 探索节点关系
MATCH (n)-[r]->(m) 
RETURN type(r), count(r) 
ORDER BY count(r) DESC

-- 查找高度连接的节点
MATCH (n)-[r]-() 
RETURN n, count(r) as degree 
ORDER BY degree DESC LIMIT 10

Análisis de esquema

-- 查看所有标签
CALL db.labels()

-- 查看所有关系类型
CALL db.relationshipTypes()

-- 查看属性键
CALL db.propertyKeys()

Desarrollo y extensión

Consulte Java_MCP_Server_Development_Guide.md en el directorio raíz del proyecto para obtener una guía de desarrollo detallada y las mejores prácticas.

Soporte técnico

  • Revise los registros de la consola para obtener información detallada sobre errores
  • Verifique el estado de la conexión a la base de datos Neo4j
  • Valide que la configuración del cliente MCP sea correcta