neo4j-mcp-skill

Neo4j MCP 技能

安装并配置官方 Neo4j MCP 服务，让 AI Agent 可以通过任何兼容 MCP 的客户端连接到 Neo4j。

适用场景

• 通过 MCP 将 Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、Kiro 或其他编辑器连接到 Neo4j
• 安装 neo4j-mcp-server 并为特定编辑器编写正确的配置
• 在 STDIO 和 HTTP 传输方式之间切换
• 启用或禁用写入权限（NEO4J_READ_ONLY）
• 排查“MCP 服务未找到”或连接错误

不适用场景

• 编写或优化 Cypher 查询 → 使用 neo4j-cypher-skill
• 配置新的 Neo4j Aura 实例 → 使用 neo4j-aura-provisioning-skill
• Agent 长期记忆 → 使用 neo4j-agent-memory-skill
• neo4j-admin / cypher-shell / aura-cli → 使用 neo4j-cli-tools-skill

---

可用的 MCP 工具

工具	类型	功能
get-schema	读取	返回标签、关系类型、属性键和索引
read-cypher	读取	执行只读 Cypher（MATCH、RETURN、SHOW）
write-cypher	写入	执行写入 Cypher（MERGE、CREATE、SET、DELETE）——当 NEO4J_READ_ONLY=true 时禁用
list-gds-procedures	读取	列出可用的 Graph Data Science 过程（需要 GDS 插件）

---

安装

步骤 1 — 安装并查找绝对路径

# Option A: pip (recommended)
pip install neo4j-mcp-server

# Option B: Download binary
# https://github.com/neo4j/mcp/releases -- macOS, Linux, Windows binaries

# Option C: Docker
docker pull neo4j/mcp

获取绝对路径 — 步骤 3 中会用到：

which neo4j-mcp          # e.g. /usr/local/bin/neo4j-mcp
                         # or:  /Users/you/project/.venv/bin/neo4j-mcp  (if installed in venv)

neo4j-mcp --version      # confirm it runs

为何绝对路径很重要：编辑器（Claude Code、Cursor、Claude Desktop）会使用自己的受限 PATH 将 MCP 服务作为子进程启动，而不是使用你的 shell PATH。在 macOS 上，GUI 应用不会继承 .zshrc 或 .zprofile。将 neo4j-mcp 用作命令会静默失败；使用 /full/path/to/neo4j-mcp 则始终有效。请务必在下面的 command 字段中使用 which neo4j-mcp 的输出。

步骤 2 — 准备凭据

# .env (gitignored)
NEO4J_URI=neo4j+s://<instance>.databases.neo4j.io   # Aura
# or bolt://localhost:7687                           # local
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=<password>
NEO4J_DATABASE=neo4j

配置编辑器前，请验证连接：

source .env
cypher-shell -a "$NEO4J_URI" -u "$NEO4J_USERNAME" -p "$NEO4J_PASSWORD" \
  "RETURN 'connected' AS status"
# If cypher-shell not available: python3 -c "
# from neo4j import GraphDatabase, __version__
# d = GraphDatabase.driver('$NEO4J_URI', auth=('$NEO4J_USERNAME','$NEO4J_PASSWORD'))
# d.verify_connectivity(); print('connected'); d.close()"

步骤 3 — 配置编辑器

选择适用于你的编辑器的配置代码块。以下配置均使用 STDIO 传输（MCP 服务作为编辑器的子进程运行）。

Claude Code — 添加到 ~/.claude/settings.json。如果文件已存在，请将 neo4j 配置块合并到现有的 mcpServers 对象中，不要替换整个文件。

{
  "mcpServers": {
    "neo4j": {
      "command": "/full/path/to/neo4j-mcp",
      "env": {
        "NEO4J_URI": "neo4j+s://<host>",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "<password>",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_READ_ONLY": "true"
      }
    }
  }
}

CLI 替代方案（仅设置命令——仍需将环境变量添加到文件中）：

claude mcp add neo4j /full/path/to/neo4j-mcp

Claude Desktop

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "neo4j": {
      "command": "/full/path/to/neo4j-mcp",
      "env": {
        "NEO4J_URI": "neo4j+s://<host>",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "<password>",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_READ_ONLY": "true"
      }
    }
  }
}

VS Code — .vscode/mcp.json（注意：使用 servers，而非 mcpServers——与其他所有编辑器不同）：

{
  "servers": {
    "neo4j": {
      "type": "stdio",
      "command": "/full/path/to/neo4j-mcp",
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "password",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_READ_ONLY": "true"
      }
    }
  }
}

Cursor — 全局：~/.cursor/mcp.json / 项目：.cursor/mcp.json（结构与 Claude Code 相同，使用 mcpServers）。

Windsurf — 全局：~/.codeium/windsurf/mcp_config.json / 项目：.windsurf/mcp_config.json（结构与 Claude Code 相同，使用 mcpServers）。

Kiro — 全局：~/.kiro/settings/mcp.json / 项目：.kiro/settings/mcp.json。支持 ${VARIABLE}，可从编辑器启动前导出到 shell 环境中的变量读取值：

{
  "mcpServers": {
    "neo4j": {
      "command": "/full/path/to/neo4j-mcp",
      "env": {
        "NEO4J_URI": "${NEO4J_URI}",
        "NEO4J_USERNAME": "${NEO4J_USERNAME}",
        "NEO4J_PASSWORD": "${NEO4J_PASSWORD}",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_READ_ONLY": "true"
      }
    }
  }
}

Cline — ~/.vscode/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json（结构与 Claude Code 相同，使用 mcpServers）。也可以通过 VS Code 设置 → Cline 扩展 → MCP Servers 面板添加。

Antigravity — 项目根目录下的 mcp_config.json（结构与 Claude Code 相同，使用 mcpServers）。

步骤 4 — 重启编辑器

编辑配置文件后，重启编辑器（如果编辑器支持热重载，也可以重新加载 MCP 服务）。确认服务显示在编辑器的 MCP 面板或工具列表中。

步骤 5 — 冒烟测试

通过 Agent 或直接通过 MCP 运行 get-schema。不要用“是否返回标签？”作为测试——空数据库不会返回任何标签，看起来与连接故障完全一样。

改用以下命令——即使数据库为空也会成功：

read-cypher: RETURN 'connected' AS status

预期结果：{ "status": "connected" }。任何结果都能确认服务正在运行且凭据有效。

如果数据库中有数据，也请运行：

get-schema

并确认它返回了预期的节点标签和关系类型。

---

HTTP 传输

HTTP 传输会将 MCP 服务作为持久网络服务运行，适用于共享服务、容器或多个客户端。

# With credentials baked in (simpler — server authenticates all clients as the same user)
neo4j-mcp \
  --neo4j-transport-mode http \
  --neo4j-http-host 127.0.0.1 \
  --neo4j-http-port 8080 \
  --neo4j-uri bolt://localhost:7687 \
  --neo4j-username neo4j \
  --neo4j-password <password> \
  --neo4j-database neo4j

HTTP 的编辑器配置（配置中不含凭据——凭据由服务保存）：

{
  "mcpServers": {
    "neo4j-http": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

单请求身份验证（从服务命令中省略 --neo4j-username/--neo4j-password）：每个客户端请求都必须包含 Authorization: Basic <base64(username:password)> 标头。使用以下命令生成该值：

echo -n "neo4j:<password>" | base64

然后添加到编辑器配置中：

{
  "headers": { "Authorization": "Basic bmVvNGo6cGFzc3dvcmQ=" }
}

安全性：绑定到 127.0.0.1，而不是 0.0.0.0。只有在需要远程访问且前方已配置 TLS + 身份验证时，才改用范围更广的网络接口。

---

环境变量

变量	必需	默认值	说明
NEO4J_URI	是	—	Aura 使用 neo4j+s://；本地使用 bolt://
NEO4J_USERNAME	是	—
NEO4J_PASSWORD	是	—
NEO4J_DATABASE	否	服务默认值	显式指定以避免路由到错误的数据库
NEO4J_READ_ONLY	否	false	设置为 true 可隐藏 write-cypher（探索时的安全默认值）

何时设置 NEO4J_READ_ONLY=false（或移除该变量）：任何需要写入数据的用例——导入、MERGE、架构变更、GDS 写回。没有写入权限时，Agent 只能看到三个工具（get-schema、read-cypher、list-gds-procedures），且 write-cypher 调用会失败。

---

APOC 要求

MCP 服务使用 APOC 进行架构内省（get-schema）。在 Aura 上，APOC 会自动包含。在自托管的 Neo4j 上，请安装 APOC 插件并将其列入白名单：

# neo4j.conf
dbms.security.procedures.unrestricted=apoc.*

验证：read-cypher: RETURN apoc.version() AS v——如果失败，get-schema 将返回不完整的结果。

---

故障排除

症状	可能原因	解决方法
编辑器中未列出服务	配置文件路径错误、JSON 格式错误，或编辑器未重启	验证 JSON（python3 -m json.tool settings.json）；确认编辑器使用了正确的文件；重启编辑器
neo4j-mcp: command not found	编辑器的 PATH 不包含二进制文件所在位置	在 command 中使用绝对路径：在终端运行 which neo4j-mcp 并粘贴结果
服务启动后立即退出	未找到 Python（pip 安装）或操作系统对应的二进制文件错误（二进制安装）	在终端手动运行命令查看错误：/full/path/neo4j-mcp --version
AuthenticationException	凭据错误	修改配置前，先使用 cypher-shell 或驱动程序验证 URI 和凭据
缺少 write-cypher 工具	NEO4J_READ_ONLY=true	如果需要写入，请移除此变量或将其设为 false
ServiceUnavailable	编辑器进程无法访问数据库	检查防火墙、VPN，或 Aura 实例是否已暂停
list-gds-procedures 返回空结果	未安装 GDS 或使用 Aura Free	GDS 需要 Aura Professional/Enterprise，或安装了插件的自托管环境

---

检查清单

• 已运行 which neo4j-mcp 并记录绝对路径——该路径应填写在 command 中，而不是 neo4j-mcp
• 已在编辑编辑器配置前验证连接（RETURN 'connected'）
• 未将凭据提交到 git；.env 已添加到 .gitignore
• 已有意设置 NEO4J_READ_ONLY——探索时设为 true，需要写入时设为 false 或不设置
• 已明确指定 NEO4J_DATABASE
• 已为目标编辑器使用正确的配置文件（VS Code 使用 servers；其他编辑器使用 mcpServers）
• 配置为有效 JSON（保存前使用 python3 -m json.tool <file> 验证）
• 配置更改后已重启编辑器
• 冒烟测试通过：read-cypher: RETURN 'connected' AS status 返回结果
• 在自行管理的环境中确认 APOC 可用：read-cypher: RETURN apoc.version()

---

参考资料

• MCP 服务文档
• MCP GitHub
• 所有 Neo4j MCP 服务
• GraphAcademy：使用 Neo4j MCP 工具进行开发