Neo4j MCP Server - 让 AI 理解你的知识图谱

Posted on

Neo4j MCP Server - 让 AI 理解你的知识图谱

官方实现 | Stars: 34 | Go | BETA 阶段

概述

Neo4j MCP Server 是 Neo4j 官方提供的 Model Context Protocol 实现，专门为图数据库设计的 AI 交互接口。它让 AI 能够通过自然语言理解和操作图数据库，无需手动编写复杂的 Cypher 查询。

这个服务器提供了三个核心工具：schema 内省、只读查询和写入查询，能够让 LLM 深入理解图数据库的结构，并执行安全的数据查询和操作。特别适合知识图谱探索、关系分析、社交网络分析等需要处理复杂关系的场景。

重要提示：当前处于 BETA 阶段，尚不适合生产环境使用。

核心特性

  • ✅ Neo4j 官方实现，与图数据库原生集成
  • 🔍 Schema 内省：自动分析图数据库结构
  • 📖 只读 Cypher 查询：安全执行查询，自动拦截危险操作
  • ✍️ 写入 Cypher 查询：支持数据修改（开发环境）
  • 🚀 Go 语言实现，高性能零依赖
  • 🌐 多部署支持：Neo4j Aura、Desktop、Self-managed
  • 🔌 兼容多种 MCP 客户端（Claude Desktop、VS Code）
  • 🔒 安全第一：自动验证和拦截危险查询

工具列表

1. get-schema

功能：内省 Neo4j 数据库的完整 schema，包括标签、关系类型和属性键

参数：无需参数

特点：

  • 只读操作，完全安全
  • 提供图数据库结构的完整视图
  • 帮助 LLM 理解数据模型和关系
  • 为后续查询提供上下文

示例输出：

1
2
3
4
5
{
  "labels": ["Person", "Movie", "Actor", "Director"],
  "relationshipTypes": ["ACTED_IN", "DIRECTED", "KNOWS", "FOLLOWS"],
  "propertyKeys": ["name", "age", "title", "year", "rating"]
}

使用场景：

  • 探索未知的图数据库结构
  • 了解可用的节点类型和关系
  • 为 AI 提供查询上下文

2. read-cypher

功能：执行只读 Cypher 查询，自动拦截写入操作

参数：

  • query (string, 必需) - Cypher 查询语句

安全限制：

  • 自动拒绝写入操作（CREATE、MERGE、SET、DELETE 等）
  • 拒绝 schema 修改（CREATE INDEX、CREATE CONSTRAINT 等）
  • 拒绝 PROFILE 查询

示例查询：

查询所有 Person 节点：

1
MATCH (n:Person) RETURN n LIMIT 10

查找特定人的朋友：

1
2
3
MATCH (p:Person)-[r:KNOWS]->(f:Person)
WHERE p.name = 'Alice'
RETURN f.name, f.age

复杂路径查询：

1
2
3
4
MATCH path = (a:Actor)-[:ACTED_IN]->(m:Movie)<-[:DIRECTED]-(d:Director)
WHERE m.year > 2020
RETURN a.name, m.title, d.name
LIMIT 5

聚合分析：

1
2
3
4
MATCH (p:Person)-[:KNOWS]->(f:Person)
RETURN p.name, count(f) as friendCount
ORDER BY friendCount DESC
LIMIT 10

3. write-cypher

功能：执行具有写入能力的 Cypher 查询

参数：

  • query (string, 必需) - Cypher 查询语句（包括写入操作）

警告：

  • ⚠️ 可能执行危险操作，建议仅在开发环境使用
  • 建议在生产环境禁用此工具
  • 执行前应审查 AI 生成的查询

示例操作：

创建节点：

1
2
CREATE (u:User {name: 'John', age: 30, email: 'john@example.com'})
RETURN u

创建关系：

1
2
3
MERGE (a:Person {name: 'Alice'})
MERGE (b:Person {name: 'Bob'})
MERGE (a)-[:KNOWS]->(b)

更新属性：

1
2
3
MATCH (u:User {name: 'John'})
SET u.age = 31, u.lastUpdated = timestamp()
RETURN u

批量创建：

1
2
3
4
5
6
UNWIND [
  {name: 'Alice', role: 'Developer'},
  {name: 'Bob', role: 'Designer'},
  {name: 'Charlie', role: 'Manager'}
] AS person
CREATE (p:Employee {name: person.name, role: person.role})

配置方式

环境变量

1
2
3
4
5
6
7
8
9
10
11
12
# Neo4j 连接 URI（必需）
NEO4J_URI=neo4j://localhost:7687
# 支持 neo4j:// 和 bolt:// 协议

# Neo4j 用户名（必需）
NEO4J_USERNAME=neo4j

# Neo4j 密码（必需）
NEO4J_PASSWORD=your-secure-password

# 数据库名称（可选，默认：neo4j）
NEO4J_DATABASE=neo4j

Claude Desktop 配置

在 claude_desktop_config.json 中添加：

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "mcpServers": {
    "neo4j": {
      "command": "neo4j-mcp",
      "env": {
        "NEO4J_URI": "neo4j://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "password",
        "NEO4J_DATABASE": "neo4j"
      }
    }
  }
}

VS Code 配置

在 mcp.json 中添加：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "servers": {
    "neo4j": {
      "type": "stdio",
      "command": "neo4j-mcp",
      "env": {
        "NEO4J_URI": "neo4j://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "password",
        "NEO4J_DATABASE": "neo4j"
      }
    }
  }
}

安装步骤

1. 下载二进制文件

从 GitHub Releases 下载对应平台的版本：

1
2
3
4
5
6
7
8
# macOS
wget https://github.com/neo4j/mcp/releases/download/v0.x.x/neo4j-mcp-darwin-amd64

# Linux
wget https://github.com/neo4j/mcp/releases/download/v0.x.x/neo4j-mcp-linux-amd64

# Windows
# 下载 neo4j-mcp-windows-amd64.exe

2. 安装到系统路径

1
2
3
4
5
6
# macOS/Linux
chmod +x neo4j-mcp
sudo mv neo4j-mcp /usr/local/bin/

# 验证安装
neo4j-mcp --version

3. 安装 APOC 插件

Neo4j MCP Server 需要 APOC 插件支持：

Neo4j Desktop:

  • 打开项目设置
  • 进入插件页面
  • 点击 APOC 插件的安装按钮

Self-managed Neo4j:

1
2
3
4
5
6
7
8
9
10
11
# 1. 下载 APOC jar
wget https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/download/5.x.x/apoc-5.x.x-all.jar

# 2. 复制到 plugins 目录
cp apoc-5.x.x-all.jar $NEO4J_HOME/plugins/

# 3. 配置 neo4j.conf
echo "dbms.security.procedures.unrestricted=apoc.*" >> $NEO4J_HOME/conf/neo4j.conf

# 4. 重启 Neo4j
neo4j restart

Neo4j Aura:

  • APOC 核心功能已预装
  • 无需额外配置

使用场景

1. 知识图谱探索

使用自然语言探索复杂的知识图谱，无需手动编写 Cypher。

示例对话：

1
2
3
4
5
6
7
用户: "我的知识图谱包含什么内容？"
AI: 使用 get-schema 工具
→ 返回所有实体类型和关系

用户: "找出所有科学家和他们的研究领域"
AI: 使用 read-cypher
→ MATCH (s:Scientist)-[:RESEARCHES]->(f:Field) RETURN s.name, f.name

2. 社交网络分析

分析社交关系、发现社区、计算影响力。

示例查询：

1
2
3
4
5
6
7
8
9
10
11
12
13
# 找出影响力最大的用户（最多好友）
MATCH (p:Person)-[:KNOWS]->(f:Person)
RETURN p.name, count(f) as friendCount
ORDER BY friendCount DESC
LIMIT 10

# 发现共同好友
MATCH (a:Person {name: 'Alice'})-[:KNOWS]->(mutual)<-[:KNOWS]-(b:Person {name: 'Bob'})
RETURN mutual.name

# 计算最短路径
MATCH path = shortestPath((a:Person {name: 'Alice'})-[:KNOWS*]-(b:Person {name: 'Charlie'}))
RETURN path, length(path)

3. 推荐系统

基于图关系生成推荐。

示例流程：

1
2
3
4
5
6
7
8
9
10
11
12
# 基于共同兴趣推荐好友
MATCH (user:Person {name: 'Alice'})-[:LIKES]->(interest)<-[:LIKES]-(other:Person)
WHERE NOT (user)-[:KNOWS]->(other)
RETURN other.name, count(interest) as commonInterests
ORDER BY commonInterests DESC
LIMIT 5

# 基于协同过滤推荐电影
MATCH (u:User {name: 'Alice'})-[:WATCHED]->(m1:Movie)<-[:WATCHED]-(other:User)-[:WATCHED]->(m2:Movie)
WHERE NOT (u)-[:WATCHED]->(m2)
RETURN m2.title, count(other) as recommendations
ORDER BY recommendations DESC

4. 企业数据分析

分析组织结构、业务流程、数据血缘。

示例场景：

1
2
3
4
5
6
7
8
9
10
11
12
# 组织架构查询
MATCH (emp:Employee)-[:REPORTS_TO*]->(manager:Employee {name: 'CEO'})
RETURN emp.name, emp.department, length((emp)-[:REPORTS_TO*]->(manager)) as level

# 项目依赖分析
MATCH (p:Project)-[:DEPENDS_ON*]->(dep:Project)
WHERE p.name = 'ProjectX'
RETURN dep.name, dep.status

# 数据血缘追踪
MATCH path = (source:DataSource)-[:FLOWS_TO*]->(target:DataWarehouse)
RETURN path

技术架构

系统架构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
┌─────────────────┐
│   MCP Client    │ (Claude Desktop / VS Code)
│  (AI Assistant) │
└────────┬────────┘
         │ MCP Protocol
         ↓
┌─────────────────┐
│ Neo4j MCP Server│
│   (Go Binary)   │
├─────────────────┤
│  • get-schema   │
│  • read-cypher  │
│  • write-cypher │
└────────┬────────┘
         │ Neo4j Driver
         ↓
┌─────────────────┐
│   Neo4j DB      │
│  + APOC Plugin  │
└─────────────────┘

查询流程

  1. Schema 分析：AI 首先调用 get-schema 了解数据结构
  2. 查询生成：基于用户问题和 schema 信息生成 Cypher
  3. 安全验证：read-cypher 自动验证和拦截危险操作
  4. 执行查询：通过 Neo4j Driver 执行 Cypher
  5. 结果返回：格式化结果返回给 AI，生成自然语言回答

技术栈

  • 语言：Go（100%）
  • 数据库：Neo4j（任何版本）
  • 依赖：APOC 插件
  • 协议：MCP stdio
  • 驱动：Neo4j Go Driver

与其他图数据库 MCP 对比

特性 Neo4j MCP Generic Graph MCP Knowledge Graph MCP
官方支持 ✅ Neo4j 官方 ❌ 社区 ❌ 社区
Schema 内省 ✅ 原生支持 ⚠️ 有限 ✅ 支持
Cypher 支持 ⭐⭐⭐⭐⭐ ⭐⭐⭐ ⭐⭐⭐⭐
安全控制 完善 基础 中等
性能 优秀（Go） 中等 中等
APOC 支持 ✅ 必需 ❌ 无 ⚠️ 可选
生产就绪 ⚠️ BETA ✅ 稳定 ⚠️ 开发中

最佳实践

1. 安全配置

创建受限用户：

1
2
3
4
5
6
7
8
9
# 创建只读用户
CREATE USER readonlyUser SET PASSWORD 'secure-password';
GRANT ROLE reader TO readonlyUser;
DENY WRITE ON GRAPH * TO readonlyUser;

# 创建受限写入用户（仅特定标签）
CREATE USER limitedUser SET PASSWORD 'secure-password';
GRANT MATCH {*} ON GRAPH * TO limitedUser;
GRANT CREATE ON GRAPH * NODES User TO limitedUser;

环境变量分离：

1
2
3
4
5
# 生产环境 - 只读用户
NEO4J_USERNAME=readonlyUser

# 开发环境 - 完整权限
NEO4J_USERNAME=neo4j

2. 查询优化

使用索引：

1
2
3
4
5
6
7
# 创建索引
CREATE INDEX person_name IF NOT EXISTS FOR (p:Person) ON (p.name);
CREATE INDEX movie_title IF NOT EXISTS FOR (m:Movie) ON (m.title);

# 查询时利用索引
MATCH (p:Person {name: 'Alice'})  // 使用索引
RETURN p

限制结果数量：

1
2
3
4
# 总是使用 LIMIT
MATCH (n:Person)
RETURN n
LIMIT 100  // 避免返回海量数据

避免全图扫描：

1
2
3
4
5
6
7
8
9
# 不好 - 全图扫描
MATCH (n)
WHERE n.age > 30
RETURN n

# 好 - 指定标签
MATCH (n:Person)
WHERE n.age > 30
RETURN n

3. APOC 最佳实践

使用 APOC 过程：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 批量操作
CALL apoc.periodic.iterate(
  "MATCH (n:Person) RETURN n",
  "SET n.processed = true",
  {batchSize: 1000}
)

# 路径扩展
MATCH (start:Person {name: 'Alice'})
CALL apoc.path.expandConfig(start, {
  relationshipFilter: 'KNOWS>',
  minLevel: 1,
  maxLevel: 3
})
YIELD path
RETURN path

4. 监控和调试

启用查询日志：

1
2
3
# neo4j.conf
dbms.logs.query.enabled=true
dbms.logs.query.threshold=1s

查看慢查询：

1
tail -f $NEO4J_HOME/logs/query.log

使用 EXPLAIN 和 PROFILE：

1
2
3
4
5
# 在开发环境测试查询性能
PROFILE
MATCH (p:Person)-[:KNOWS*2]->(f)
WHERE p.name = 'Alice'
RETURN f.name

常见问题

Q: 如何部署本地 Neo4j 数据库？

Docker 方式：

1
2
3
4
5
docker run \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password \
  -e NEO4J_PLUGINS='["apoc"]' \
  neo4j:latest

Neo4j Desktop：

  1. 下载并安装 Neo4j Desktop
  2. 创建新项目和数据库
  3. 在插件页面安装 APOC
  4. 启动数据库

Q: 支持 Neo4j Aura 云数据库吗？

是的，完全支持。配置示例：

1
2
3
4
NEO4J_URI=neo4j+s://xxxxx.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-aura-password
NEO4J_DATABASE=neo4j

Q: 如何导入现有数据？

CSV 导入：

1
2
LOAD CSV WITH HEADERS FROM 'file:///users.csv' AS row
CREATE (p:Person {name: row.name, age: toInteger(row.age)})

JSON 导入（APOC）：

1
2
3
CALL apoc.load.json('https://api.example.com/data.json')
YIELD value
CREATE (n:Node {data: value})

批量导入工具：

1
2
3
neo4j-admin import \
  --nodes=Person=persons.csv \
  --relationships=KNOWS=knows.csv

Q: 性能如何？

  • Schema 查询: <10ms
  • 简单查询: 10-100ms
  • 复杂图遍历: 100ms-1s
  • 写入操作: 10-50ms/节点

性能取决于：

  • 数据库规模
  • 查询复杂度
  • 索引配置
  • 硬件资源

Q: 生产环境可以使用吗？

⚠️ 当前不建议。项目处于 BETA 阶段，建议：

  • 开发环境：✅ 可以使用
  • 测试环境：⚠️ 谨慎使用
  • 生产环境：❌ 等待稳定版本

评分详情

维度 评分 说明
功能性 4.5/5.0 核心功能完善，BETA 阶段限制生产使用
文档质量 4.3/5.0 README 清晰，但缺少详细教程
社区活跃度 4.6/5.0 Neo4j 官方维护，社区支持良好
维护状态 4.4/5.0 活跃开发中，定期更新
代码质量 4.7/5.0 Go 语言实现，代码质量高
综合评分 4.5/5.0 优秀的图数据库 MCP 实现

总结

Neo4j MCP Server 是连接 AI 和图数据库的强大桥梁。它让 LLM 能够理解和操作复杂的关系数据，为知识图谱、社交网络、推荐系统等应用提供了自然语言接口。

推荐指数: ⭐⭐⭐⭐ (4/5) - BETA 阶段扣 1 星

适合你的情况：

  • ✅ 使用 Neo4j 图数据库
  • ✅ 需要 AI 辅助图数据探索
  • ✅ 构建知识图谱应用
  • ✅ 关系数据分析和查询
  • ✅ 开发和测试环境

不适合的情况：

  • ❌ 生产环境（当前 BETA）
  • ❌ 简单的键值存储需求
  • ❌ 不使用 Neo4j 数据库
  • ❌ 不需要关系型查询

相关资源

更新时间: 2025-10-14
数据来源: GitHub, 质量评分: 4.5/5.0

© 2025 Generative AI Discovery All Rights Reserved.
Theme by hiero