用途
Neo4j MCP Skill 用于安装和配置官方 Neo4j MCP 服务器（neo4j/mcp），使 AI 智能体能够通过任意兼容 MCP 的客户端连接 Neo4j 数据库。它适合以下场景：将 Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、Kiro 等编辑器接入 Neo4j；安装 neo4j-mcp-server 并为特定编辑器编写正确配置；在 stdio 与 HTTP 传输之间切换；启用或禁用写访问（NEO4J_READ_ONLY）；排查“MCP server not found”或连接错误。
该技能不适用于：编写或优化 Cypher 查询（应使用 neo4j-cypher-skill）、创建新的 Neo4j Aura 实例（应使用 neo4j-aura-provisioning-skill）、智能体长期记忆（应使用 neo4j-agent-memory-skill）、以及 neo4j-admin / cypher-shell / aura-cli 等命令行工具（应使用 neo4j-cli-tools-skill）。
主要能力
该技能围绕官方 Neo4j MCP 服务器提供的四个工具展开：
- get-schema（读）：返回标签、关系类型、属性键和索引。
- read-cypher（读）：执行只读 Cypher（MATCH、RETURN、SHOW）。
- write-cypher（写）：执行写 Cypher（MERGE、CREATE、SET、DELETE），当 NEO4J_READ_ONLY=true 时被禁用。
- list-gds-procedures（读）：列出可用的图数据科学（GDS）过程，需要 GDS 插件。
使用方式
安装有三种方式：pip 安装（推荐，pip install neo4j-mcp-server）、下载二进制（来自 GitHub releases，提供 macOS、Linux、Windows 版本）、或 Docker（docker pull neo4j/mcp）。安装后需用 which neo4j-mcp 获取绝对路径，并用 neo4j-mcp --version 确认可运行。使用绝对路径很重要，因为编辑器以子进程方式启动 MCP 服务器，使用的是其自身受限的 PATH，而非 shell 的 PATH；在 macOS 上 GUI 应用不会继承 .zshrc 或 .zprofile，直接写 neo4j-mcp 会静默失败。
凭据准备：在 .env（应加入 .gitignore）中设置 NEO4J_URI、NEO4J_USERNAME、NEO4J_PASSWORD、NEO4J_DATABASE。配置编辑器前先用 cypher-shell 或 Python 驱动验证连通性。
编辑器配置：各编辑器均使用 STDIO 传输（MCP 服务器作为编辑器的子进程运行）。Claude Code 写入 ~/.claude/settings.json，若文件已存在需将 neo4j 块合并进现有 mcpServers 对象，不要替换整个文件；也可用 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。VS Code 使用 .vscode/mcp.json，注意其键名为 servers 而非 mcpServers。Cursor 使用 ~/.cursor/mcp.json 或项目内 .cursor/mcp.json。Windsurf 使用 ~/.codeium/windsurf/mcp_config.json 或项目内 .windsurf/mcp_config.json。Kiro 使用 ~/.kiro/settings/mcp.json 或项目内 .kiro/settings/mcp.json，支持 ${VARIABLE} 从编辑器启动前导出的 shell 环境变量取值。Cline 使用 ~/.vscode/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json，或通过 VS Code 设置中的 Cline 扩展 MCP Servers 面板添加。Antigravity 使用项目根目录的 mcp_config.json。
修改配置后需重启编辑器（或热重载 MCP 服务器），并确认服务器出现在编辑器的 MCP 面板或工具列表中。冒烟测试建议使用 read-cypher: RETURN 'connected' AS status，预期返回 { "status": "connected" }；不要用“是否返回标签”作为测试，因为空数据库不返回标签，看起来与连接损坏相同。若数据库有数据，再运行 get-schema 确认返回预期的节点标签和关系类型。
HTTP 传输：将 MCP 服务器作为常驻网络服务运行，适合共享服务器、容器或多客户端。可用 --neo4j-transport-mode http、--neo4j-http-host、--neo4j-http-port 等参数启动，凭据可内置在服务器命令中（更简单，所有客户端以同一用户认证），也可省略用户名密码改为每请求认证，此时每个客户端请求需带 Authorization: Basic <base64(username:password)> 头，可用 echo -n "neo4j:<password>" | base64 生成。编辑器配置中 HTTP 类型写 "type": "http" 与 "url": "http://127.0.0.1:8080/mcp"，凭据放在 headers 中。安全上应绑定 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，适合探索场景）。需要写入数据（导入、MERGE、模式变更、GDS 回写）时应设为 false 或移除该变量；否则智能体只能看到三个工具，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 会返回不完整结果。
适用场景与限制
适用场景包括：为各类编辑器接入 Neo4j MCP、在只读探索与可写操作之间切换、搭建共享的 HTTP MCP 服务、以及排查连接与配置问题。
限制与注意事项：该技能不涉及 Cypher 查询编写与优化、Aura 实例创建、智能体长期记忆、命令行工具使用。list-gds-procedures 需要 GDS 插件，Aura Free 不支持，需 Aura Professional/Enterprise 或自管理加插件。故障排查方面，服务器未列出通常是配置文件路径错误、JSON 格式错误或编辑器未重启；neo4j-mcp: command not found 是编辑器 PATH 不含二进制位置，应使用绝对路径；服务器启动后立即退出可能是 Python 未找到或二进制与操作系统不匹配；AuthenticationException 是凭据错误；write-cypher 工具缺失是 NEO4J_READ_ONLY=true；ServiceUnavailable 是数据库从编辑器进程不可达，需检查防火墙、VPN 或 Aura 实例是否暂停。配置检查清单包括：确认 which neo4j-mcp 的绝对路径、编辑配置前验证连通性、凭据不提交到 git、有意设置 NEO4J_READ_ONLY、显式指定 NEO4J_DATABASE、使用目标编辑器的正确配置文件（VS Code 用 servers，其余用 mcpServers）、用 python3 -m json.tool 验证 JSON、重启编辑器、通过冒烟测试、自管理环境确认 APOC 可用。