Neo4j MCP Server

Um serviço de consulta somente leitura para bancos de dados gráficos Neo4j.

GitHubExperimente este MCPPatrocinado

Documentação

Documentação de Uso do Neo4j MCP Server

Introdução

O Neo4j MCP Server é um serviço de consulta somente leitura para o banco de dados Neo4j, construído com Spring AI e Model Context Protocol (MCP). Ele fornece aos assistentes de IA a capacidade de acessar com segurança o banco de dados de grafos Neo4j.

Início Rápido

1. Requisitos de Ambiente

  • Java 21+
  • Maven 3.6+
  • Banco de dados Neo4j (local ou remoto)

2. Configurar Conexão com o Banco de Dados

Edite src/main/resources/application.properties:

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

3. Iniciar o Servidor

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

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

Após iniciar com sucesso, você verá:

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

Ferramentas Disponíveis

Ferramentas de Consulta Principais

1. executeCypher

Executa consultas Cypher somente leitura

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

2. getDatabaseInfo

Obtém informações completas do banco de dados (versão, estatísticas, esquema, etc.)

3. getNodeLabels

Obtém a lista de todos os rótulos de nós

4. getRelationshipTypes

Obtém a lista de todos os tipos de relacionamento

5. getPropertyKeys

Obtém a lista de todas as chaves de propriedade

Ferramentas de Consulta de Esquema

6. getSchemaInfo

Obtém informações sobre restrições e índices do banco de dados

7. findNodesByLabel

Encontra nós por rótulo, com suporte a filtro de propriedades

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

Ferramentas de Travessia de Grafo

8. getRelationshipsBetweenNodes

Obtém os relacionamentos entre dois nós

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

9. getNodeNeighborhood

Obtém a vizinhança de um nó (nós conectados)

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

10. searchNodesByText

Pesquisa texto nas propriedades dos nós

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

Conexão com Cliente MCP

Conexão no Modo STDIO

Este servidor habilita o modo de transporte STDIO por padrão e pode ser conectado diretamente por clientes MCP:

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

Integração com Claude Desktop

Adicione no arquivo de configuração do Claude Desktop:

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

Recursos de Segurança

Proteção Somente Leitura

  • ✅ Apenas operações de leitura como MATCH, RETURN, WITH, OPTIONAL MATCH, UNWIND são permitidas
  • ❌ Operações de escrita como CREATE, MERGE, DELETE, SET, DROP são proibidas
  • ✅ Alguns comandos SHOW são permitidos (CONSTRAINTS, INDEXES, PROCEDURES, FUNCTIONS)

Limitações de Consulta

  • Número máximo de registros retornados por consulta: 1000
  • Tempo limite de consulta: 30 segundos
  • Número máximo de conexões no pool: 50

Parâmetros de Configuração

Configuração do 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

Configuração de Conexão 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

Solução de Problemas

Perguntas Frequentes

  1. Falha de conexão

    • Verifique se o serviço Neo4j está em execução
    • Valide os parâmetros de conexão (URI, nome de usuário, senha)
    • Confirme as configurações do firewall

  2. Ferramenta não registrada

    • Verifique as informações de "Registered tools" no log de inicialização
    • Confirme se a configuração automática do Spring AI está funcionando corretamente

  3. Consulta rejeitada

    • Confirme se a consulta é uma operação somente leitura
    • Verifique se a sintaxe Cypher está correta

Ajuste do Nível de Log

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

Exemplos de Uso

Exploração Básica de Grafo

-- 查看数据库概览
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álise de Esquema

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

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

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

Desenvolvimento e Extensão

Consulte o Java_MCP_Server_Development_Guide.md no diretório raiz do projeto para obter um guia detalhado de desenvolvimento e melhores práticas.

Suporte Técnico

  • Verifique os logs do console para obter informações detalhadas de erro
  • Verifique o status da conexão com o banco de dados Neo4j
  • Valide se a configuração do cliente MCP está correta