Neo4j MCP Server 使用文档

简介

Neo4j MCP Server 是基于 Spring AI 和 Model Context Protocol (MCP) 构建的 Neo4j 数据库只读查询服务。它为 AI 助手提供了安全访问 Neo4j 图数据库的能力。

快速开始

1. 环境要求

• Java 21+
• Maven 3.6+
• Neo4j 数据库 (本地或远程)

2. 配置数据库连接

编辑 src/main/resources/application.properties:

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

3. 启动服务器

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

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

启动成功后会看到：

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

可用工具

核心查询工具

1. executeCypher

执行只读 Cypher 查询

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

2. getDatabaseInfo

获取数据库完整信息（版本、统计、模式等）

3. getNodeLabels

获取所有节点标签列表

4. getRelationshipTypes

获取所有关系类型列表

5. getPropertyKeys

获取所有属性键列表

模式查询工具

6. getSchemaInfo

获取数据库约束和索引信息

7. findNodesByLabel

按标签查找节点，支持属性过滤

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

图遍历工具

8. getRelationshipsBetweenNodes

获取两个节点间的关系

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

9. getNodeNeighborhood

获取节点的邻域（连接的节点）

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

10. searchNodesByText

在节点属性中搜索文本

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

MCP 客户端连接

STDIO 模式连接

本服务器默认启用 STDIO 传输模式，可以直接被 MCP 客户端连接：

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

Claude Desktop 集成

在 Claude Desktop 配置文件中添加：

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

安全特性

只读保护

• ✅ 仅允许 MATCH, RETURN, WITH, OPTIONAL MATCH, UNWIND 等读取操作
• ❌ 禁止 CREATE, MERGE, DELETE, SET, DROP 等写入操作
• ✅ 允许部分 SHOW 命令（CONSTRAINTS, INDEXES, PROCEDURES, FUNCTIONS）

查询限制

• 单次查询最大返回记录数：1000
• 查询超时时间：30秒
• 连接池最大连接数：50

配置参数

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

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

故障排查

常见问题

1. 连接失败

   • 检查 Neo4j 服务是否启动
   • 验证连接参数（URI、用户名、密码）
   • 确认防火墙设置

2. 工具未注册

   • 查看启动日志中的 "Registered tools" 信息
   • 确认 Spring AI 自动配置正常工作

3. 查询被拒绝

   • 确认查询是只读操作
   • 检查 Cypher 语法是否正确

日志级别调整

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

示例用法

基本图探索

-- 查看数据库概览
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

模式分析

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

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

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

开发和扩展

参考项目根目录的 Java_MCP_Server_Development_Guide.md 获取详细的开发指南和最佳实践。

技术支持

• 查看控制台日志获取详细错误信息
• 检查 Neo4j 数据库连接状态
• 验证 MCP 客户端配置正确性