trackmcp
Back to directory
STUzhy

java-neo4j-mcp

View on GitHub

Neo4j MCP Server

0 stars JavaOthers Updated Jun 17, 2025

Documentation

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`:

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

3. 启动服务器

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

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

启动成功后会看到:

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

可用工具

核心查询工具

1. executeCypher

执行只读 Cypher 查询

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

2. getDatabaseInfo

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

3. getNodeLabels

获取所有节点标签列表

4. getRelationshipTypes

获取所有关系类型列表

5. getPropertyKeys

获取所有属性键列表

模式查询工具

6. getSchemaInfo

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

7. findNodesByLabel

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

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

图遍历工具

8. getRelationshipsBetweenNodes

获取两个节点间的关系

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

9. getNodeNeighborhood

获取节点的邻域(连接的节点)

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

10. searchNodesByText

在节点属性中搜索文本

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

MCP 客户端连接

STDIO 模式连接

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

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

Claude Desktop 集成

在 Claude Desktop 配置文件中添加:

json
{
  "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 服务器配置

properties
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 连接配置

properties
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. 连接失败

    2. 工具未注册

      3. 查询被拒绝

        日志级别调整

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

        示例用法

        基本图探索

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

        模式分析

        cypher
        -- 查看所有标签
        CALL db.labels()
        
        -- 查看所有关系类型
        CALL db.relationshipTypes()
        
        -- 查看属性键
        CALL db.propertyKeys()

        开发和扩展

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

        技术支持

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

        Frequently asked questions

        What is java-neo4j-mcp?

        java-neo4j-mcp is Neo4j MCP Server

        How do I install java-neo4j-mcp?

        Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

        Is java-neo4j-mcp open source?

        Yes — it is hosted on GitHub at https://github.com/STUzhy/java-neo4j-mcp.

        Related MCP tools

        Run your own MCP server? See who uses it and what to fix.

        Measure it with TrackMCP