Neo4j MCP — 使用场景, 安装 & 实时演示

为什么要用

核心特性

执行任意 Cypher 读写查询
Schema 内省：标签、关系类型、属性键、约束、索引
支持 Neo4j Community、Enterprise、AuraDB 和 Neo4j Desktop
单独的 Aura-admin server 用于在 Neo4j Aura 中配置实例
工具面积小且专注 — 没有魔法；你完全掌控每一个 Cypher

实时演示

实际使用效果

neo4j.replay ▶ 就绪

0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "neo4j": {
      "command": "uvx",
      "args": [
        "mcp-neo4j-cypher"
      ]
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "neo4j": {
      "command": "uvx",
      "args": [
        "mcp-neo4j-cypher"
      ]
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "neo4j": {
      "command": "uvx",
      "args": [
        "mcp-neo4j-cypher"
      ]
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标，然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "neo4j": {
      "command": "uvx",
      "args": [
        "mcp-neo4j-cypher"
      ]
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "neo4j",
      "command": "uvx",
      "args": [
        "mcp-neo4j-cypher"
      ]
    }
  ]
}

Continue 使用服务器对象数组，而非映射。

~/.config/zed/settings.json

{
  "context_servers": {
    "neo4j": {
      "command": {
        "path": "uvx",
        "args": [
          "mcp-neo4j-cypher"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add neo4j -- uvx mcp-neo4j-cypher

一行命令搞定。用 claude mcp list 验证，claude mcp remove 卸载。

使用场景

实战用法： Neo4j

5 分钟内探索陌生的 graph schema

👤 接手 Neo4j DB 的工程师 / 分析师 ⏱ ~15 min beginner

何时使用： 你接手一个没有文档的 graph DB。在写有用的查询之前，你需要建立心智模型。

前置条件

Neo4j Bolt URL + 用户/密码 — NEO4J_URI=bolt://host:7687, NEO4J_USERNAME, NEO4J_PASSWORD
建议用只读用户来探索 — CREATE USER claude SET PASSWORD '...' SET ROLES reader

步骤

获取 schema 概览

调用 get_neo4j_schema。总结节点标签、关系类型以及最常见的 (label)-[rel]->(label) 模式。✓ 已复制

→ Schema 摘要和样本三元组
采样代表性节点

对于 3 个最常见的标签，各执行一次 MATCH (n:Label) RETURN n LIMIT 3。描述每个标签似乎代表什么。✓ 已复制

→ 标签的语义描述
绘制可能的 ER 模型

基于 schema 和样本，用文字描述这个图的'实体'故事。主要对象是什么，什么连接到它，什么是外围的？✓ 已复制

→ 清晰的领域模型描述

结果： 一份单页的领域模型，可以与原始作者验证。

注意事项

采样很小的图给出误导性的模式 — 还要执行 MATCH (n)-[r]->() RETURN type(r), count(*) 来看哪些关系占主导

搭配使用： filesystem

编写 graph 查询来检测欺诈团伙

👤 风险 / 欺诈分析师 ⏱ ~40 min advanced

何时使用： 你怀疑跨账户的共享设备或共享地址欺诈团伙。

前置条件

包含 User、Device、Address、Payment 节点和 :USED、:LIVES_AT、:PAID 关系的图 — 典型的欺诈图形状

步骤

查找共享设备

查找过去 30 天被 3 个或以上不同用户使用的设备。返回 device_id + user_ids 列表 + 每对的最后使用时间。✓ 已复制

→ 团伙候选
按连通分量大小评分

使用 GDS 或纯 Cypher，计算 User-(:USED)-Device-(:USED)-User 上的连通分量。返回大小最大的前 10 个分量。✓ 已复制

→ 可疑集群
生成可操作的列表

对于每个顶级集群，列出不同的用户、交易总额和最早/最新的活动。标记 > $10k 的集群为高优先级审查。✓ 已复制

→ 分析师队列条目

结果： 一份优先级化的欺诈审查队列，保留确切的 Cypher。

注意事项

在枢纽上的朴素遍历会爆炸（共享公共 wifi 设备有 10k 用户） — 在遍历前限制深度并按度数过滤掉枢纽节点

搭配使用： postgres

原型化一个内容推荐查询

👤 构建'其他喜欢的用户'的产品工程师 ⏱ ~30 min intermediate

何时使用： 你有 User-LIKED->Item，想推荐来自相似用户的项目。

步骤

选择一个用户并查找邻近用户

对于用户 <id>，查找共享最多 LIKED 项目的 20 个用户。返回 user_id 和重叠计数。✓ 已复制

→ 排序后的相似用户
推荐那些用户喜欢的项目

对于这前 20 个相似用户，列出他们喜欢但 <id> 还没喜欢的项目。按喜欢它的相似用户数排序。✓ 已复制

→ 前 N 个推荐
将其转换为可重用查询

参数化为可调用的 Cypher，使用 $user_id；添加加速所需的索引。✓ 已复制

→ 生产就绪的查询 + CREATE INDEX 语句

结果： 一个工作中的协同过滤查询，快到可以在线服务。

注意事项

忘记 :User(id) 上的索引使启动查询变成线性的 — CREATE INDEX FOR (u:User) ON (u.id) 并用 EXPLAIN 确认它被使用了

从临时表将关系型数据加载到 Neo4j

👤 从 SQL 迁移到 graph 的数据工程师 ⏱ ~40 min advanced

何时使用： 你在 Postgres 中有 users + follows，想要 graph 表示。

前置条件

可写的 Neo4j 用户 — 在目标数据库上有 CREATE 角色

步骤

规划节点/边映射

给定表 users(id, name) 和 follows(from_id, to_id)，提议 Neo4j 模型。标签？关系方向？✓ 已复制

→ (:User {id,name})-[:FOLLOWS]->(:User)
首先创建约束

生成 CREATE CONSTRAINT FOR (u:User) REQUIRE u.id IS UNIQUE。执行它。✓ 已复制

→ 约束已创建
用 MERGE 批量加载

从提供的用户行，运行 UNWIND $rows AS r MERGE (:User {id:r.id}) ...，然后用 MERGE (a)-[:FOLLOWS]->(b) 处理 follows。每次批处理 10k。✓ 已复制

→ 所有行幂等加载

结果： 一个可重新运行的 ETL，将你的关系型数据加载到 graph 形状。

注意事项

用 CREATE 而非 MERGE 会在重新运行时创建重复节点 — 对于 upsert 始终使用 MERGE，在批量 MERGE 前需要唯一性约束以提高速度

搭配使用： postgres

回答关于知识图谱的自然语言问题

👤 拥有领域 KG 的内部团队 ⏱ ~25 min intermediate

何时使用： 你构建了一个小本体（产品、特性、客户），想让 Claude 回答'哪些客户使用特性 X'，而不需要学习 Cypher。

步骤

让 Claude 理解 schema

这是 schema [粘贴 get_neo4j_schema 输出]。从现在开始，运行我的问题前先将其翻译为 Cypher。✓ 已复制

→ Claude 回应 schema 理解
提问，获得 Cypher + 答案

哪些客户在上个季度使用了'export-csv'特性？✓ 已复制

→ 显示 Cypher + 结果表
当 Cypher 错误时进行精炼

那个 Cypher 错过了到 Session 的 :USED 关系。修复它使其通过 sessions。✓ 已复制

→ 修正的 Cypher 重新运行

结果： 一个轻量级的 NL-to-Cypher 接口，适合非技术团队成员。

注意事项

Claude 发明了不存在的标签 — 固定它：'只使用提供的 schema 中的标签/关系；否则说未知'

组合

与其他 MCP 搭配，撬动十倍杠杆

neo4j + postgres

将关系型数据同步到 graph 表示

从 Postgres 拉取 users + follows，然后 MERGE 到 Neo4j 为 (:User)-[:FOLLOWS]->(:User)。✓ 已复制

neo4j + qdrant

图增强 RAG：使用 Qdrant 进行语义召回，Neo4j 进行精确关系

Qdrant 查找与问题相似的文档；然后从匹配的实体遍历 Neo4j 来拉取答案的结构化事实。✓ 已复制

neo4j + filesystem

将 Cypher 生成的报告导出为 CSV/Markdown

运行欺诈团伙 Cypher，将前 50 个集群导出为 /reports/fraud-<date>.csv。✓ 已复制

工具

此 MCP 暴露的能力

工具	输入参数	何时调用	成本
get_neo4j_schema		总是在新 session 中最先调用	free
read_neo4j_cypher	query: str, params?: object	任何 MATCH / RETURN — 只读	free
write_neo4j_cypher	query: str, params?: object	CREATE/MERGE/SET/DELETE — 变更	free

成本与限制

运行它的成本

API 配额: 受你的 Neo4j 实例限制。Aura Free：200k 节点/400k 关系。
每次调用 Token 数: Schema：~500 tokens。查询结果：取决于行+属性。
费用: Community / 自托管免费。Aura Free 版本存在。Aura 付费从 ~$65/月开始。
提示: 在大图上总是先使用 EXPLAIN；在启动标签上的缺失索引会将 5ms 查询变成 5 分钟扫描。

安全

权限、密钥、影响范围

最小权限： 读取 role 用于只读探索

凭据存储： NEO4J_URI、NEO4J_USERNAME、NEO4J_PASSWORD 在环境变量中

数据出站： 到你的 Neo4j 的直接 Bolt 连接（自托管或 Aura）

切勿授予： admin 角色 PUBLIC 写入权限

DROP DATABASE 和 CREATE CONSTRAINT 需要提升的角色 — 将这些保留在单独的仅限管理员连接配置文件上。
对于任何不显式需要写入的 session，用 reader-role 账户运行 MCP。

故障排查

常见错误与修复

ServiceUnavailable: 连接被拒绝

Neo4j 未运行或 Bolt 端口错误（默认 7687）。用 cypher-shell -a bolt://host:7687 检查。

验证： nc -zv host 7687

Neo.ClientError.Security.Unauthorized

用户名/密码错误。从管理员 session 通过 CALL dbms.security.changePassword('new') 重置。

Neo.ClientError.Statement.SyntaxError

Claude 的 Cypher 有拼写错误 — 粘贴确切的错误，请求修正后的查询。

写入失败: 在只读模式下不允许写操作

你用 reader role 连接；切换到有 WRITE 权限的用户或使用单独的写入连接。

替代方案

Neo4j 对比其他方案

替代方案	何时用它替代	权衡
Memgraph MCP	你需要流式图分析；Memgraph 兼容 Cypher	生态较小，托管选项较少
ArangoDB MCP	你想要多模型（图 + 文档 + KV）	用 AQL 代替 Cypher；有学习曲线
Postgres + Apache AGE	你主要是关系型的，有一些图需求	大遍历时图性能比原生 Neo4j 差

Neo4j

为什么要用

核心特性

实时演示

实际使用效果

安装

选择你的客户端

使用场景

实战用法： Neo4j

前置条件

步骤

注意事项

前置条件

步骤

注意事项

步骤

注意事项

前置条件

步骤

注意事项

步骤

注意事项

组合

与其他 MCP 搭配，撬动十倍杠杆

工具

此 MCP 暴露的能力

成本与限制

运行它的成本

安全

权限、密钥、影响范围

故障排查

常见错误与修复

替代方案

Neo4j 对比其他方案

更多

资源