neo4j-mcp-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Neo4j MCP Skill

Neo4j MCP 技能

Installs and configures the official Neo4j MCP server so AI agents can connect to Neo4j via any MCP-compatible client.

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

When to Use

适用场景

Connecting Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Kiro, or another editor to Neo4j via MCP
Installing
```
neo4j-mcp-server
```
and writing the correct config for a specific editor
Switching between stdio and HTTP transport
Enabling or disabling write access (
```
NEO4J_READ_ONLY
```
)
Troubleshooting "MCP server not found" or connection errors

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

When NOT to Use

不适用场景

Writing or optimizing Cypher queries → use
```
neo4j-cypher-skill
```
Provisioning a new Neo4j Aura instance → use
```
neo4j-aura-provisioning-skill
```
Agent long-term memory → use
```
neo4j-agent-memory-skill
```
neo4j-admin / cypher-shell / aura-cli → use
```
neo4j-cli-tools-skill
```

编写或优化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
```

Available MCP Tools

可用MCP工具

Tool	Type	What it does
`get-schema`	read	Returns labels, relationship types, property keys, and indexes
`read-cypher`	read	Executes read-only Cypher ( `MATCH` , `RETURN` , `SHOW` )
`write-cypher`	write	Executes write Cypher ( `MERGE` , `CREATE` , `SET` , `DELETE` ) — disabled when `NEO4J_READ_ONLY=true`
`list-gds-procedures`	read	Lists available Graph Data Science procedures (requires GDS plugin)

工具	类型	功能
`get-schema`	只读	返回标签、关系类型、属性键和索引
`read-cypher`	只读	执行只读Cypher语句（ `MATCH` 、 `RETURN` 、 `SHOW` ）
`write-cypher`	可写	执行写入型Cypher语句（ `MERGE` 、 `CREATE` 、 `SET` 、 `DELETE` ）——当 `NEO4J_READ_ONLY=true` 时会被禁用
`list-gds-procedures`	只读	列出可用的图数据科学（GDS）过程（需要安装GDS插件）

Installation

安装步骤

Step 1 — Install and find the absolute path

步骤1 — 安装并获取绝对路径

bash

undefined

bash

undefined

Option A: pip (recommended)

选项A：pip（推荐）

pip install neo4j-mcp-server

Option B: Download binary

选项B：下载二进制文件

https://github.com/neo4j/mcp/releases -- macOS, Linux, Windows binaries

https://github.com/neo4j/mcp/releases -- 提供macOS、Linux、Windows二进制文件

Option C: Docker

选项C：Docker

docker pull neo4j/mcp


**Get the absolute path — you will need this in Step 3:**
```bash
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

Why absolute path matters: editors (Claude Code, Cursor, Claude Desktop) spawn the MCP server as a subprocess using their own restricted PATH — not your shell's PATH. On macOS, GUI apps do not inherit
.zshrc
or
.zprofile
. Using
neo4j-mcp
as the command will silently fail; using
/full/path/to/neo4j-mcp
always works. Always use the output of
which neo4j-mcp
in the
command
field below.

docker pull neo4j/mcp


**获取绝对路径——步骤3会用到：**
```bash
which neo4j-mcp          # 示例：/usr/local/bin/neo4j-mcp
                         # 或：/Users/you/project/.venv/bin/neo4j-mcp （如果安装在虚拟环境中）

neo4j-mcp --version      # 确认程序可运行

为什么绝对路径很重要：编辑器（Claude Code、Cursor、Claude Desktop）会使用自身受限的PATH环境变量来启动MCP服务器子进程——而非你的Shell的PATH。在macOS上，GUI应用不会继承
.zshrc
或
.zprofile
中的配置。直接使用
neo4j-mcp
命令会静默失败；而使用
/完整路径/neo4j-mcp
则始终有效。请务必将
which neo4j-mcp
的输出填入下方的
command
字段。

Step 2 — Prepare credentials

步骤2 — 准备凭证

bash

undefined

bash

undefined

.env (gitignored)

.env（已加入git忽略）

NEO4J_URI=neo4j+s://<instance>.databases.neo4j.io # Aura

NEO4J_URI=neo4j+s://<instance>.databases.neo4j.io # Aura实例

or bolt://localhost:7687 # local

或 bolt://localhost:7687 # 本地实例

NEO4J_USERNAME=neo4j NEO4J_PASSWORD=<password> NEO4J_DATABASE=neo4j


Verify connectivity before configuring the editor:
```bash
source .env
cypher-shell -a "$NEO4J_URI" -u "$NEO4J_USERNAME" -p "$NEO4J_PASSWORD" \
  "RETURN 'connected' AS status"

NEO4J_USERNAME=neo4j NEO4J_PASSWORD=<password> NEO4J_DATABASE=neo4j


在配置编辑器前先验证连接性：
```bash
source .env
cypher-shell -a "$NEO4J_URI" -u "$NEO4J_USERNAME" -p "$NEO4J_PASSWORD" \
  "RETURN 'connected' AS status"

If cypher-shell not available: python3 -c "

如果没有cypher-shell：python3 -c "

from neo4j import GraphDatabase, version

d = GraphDatabase.driver('$NEO4J_URI', auth=('$NEO4J_USERNAME','$NEO4J_PASSWORD'))

d.verify_connectivity(); print('connected'); d.close()"

undefined

undefined

Step 3 — Configure your editor

步骤3 — 配置编辑器

Pick the config block for your editor. All use STDIO transport (the MCP server runs as a subprocess of the editor).

Claude Code — add to

~/.claude/settings.json

. If the file already exists, merge the

neo4j

block into the existing

mcpServers

object — do not replace the whole file.

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"
      }
    }
  }
}

CLI alternative (sets command only — you still need to add env vars to the file):

bash

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

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

(note: uses

servers

, not

mcpServers

— different from all other editors):

json

{
  "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 — global:

~/.cursor/mcp.json

/ project:

.cursor/mcp.json

(same structure as Claude Code, uses

mcpServers

Windsurf — global:

~/.codeium/windsurf/mcp_config.json

/ project:

.windsurf/mcp_config.json

(same structure as Claude Code, uses

mcpServers

Kiro — global:

~/.kiro/settings/mcp.json

/ project:

.kiro/settings/mcp.json

. Supports

${VARIABLE}

to pull from the shell environment exported before the editor launched:

json

{
  "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

(same structure as Claude Code, uses

mcpServers

). Or add via VS Code settings → Cline extension → MCP Servers panel.

Antigravity —

mcp_config.json

at project root (same structure as Claude Code, uses

mcpServers

选择对应编辑器的配置块。所有配置均使用STDIO传输（MCP服务器作为编辑器的子进程运行）。

Claude Code — 添加到

~/.claude/settings.json

。如果文件已存在，请将

neo4j

块合并到现有的

mcpServers

对象中——不要替换整个文件。

json

{
  "mcpServers": {
    "neo4j": {
      "command": "/完整路径/neo4j-mcp",
      "env": {
        "NEO4J_URI": "neo4j+s://<host>",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "<password>",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_READ_ONLY": "true"
      }
    }
  }
}

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

bash

claude mcp add neo4j /完整路径/neo4j-mcp

Claude Desktop

macOS：

~/Library/Application Support/Claude/claude_desktop_config.json

Windows：

%APPDATA%\Claude\claude_desktop_config.json

json

{
  "mcpServers": {
    "neo4j": {
      "command": "/完整路径/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

——与其他所有编辑器不同）：

json

{
  "servers": {
    "neo4j": {
      "type": "stdio",
      "command": "/完整路径/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环境中读取变量：

json

{
  "mcpServers": {
    "neo4j": {
      "command": "/完整路径/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服务器面板添加。

Antigravity — 项目根目录下的

mcp_config.json

（与Claude Code结构相同，使用

mcpServers

）。

Step 4 — Restart the editor

步骤4 — 重启编辑器

After editing the config file, restart the editor (or reload the MCP server if the editor supports hot-reload). Verify the server appears in the editor's MCP panel or tool list.

编辑配置文件后，重启编辑器（如果编辑器支持热重载，也可以重新加载MCP服务器）。验证服务器是否出现在编辑器的MCP面板或工具列表中。

Step 5 — Smoke test

步骤5 — 冒烟测试

Run

get-schema

via the agent or directly via MCP. Do not use "does it return labels?" as the test — an empty database returns no labels and looks identical to a broken connection.

Use this instead — it succeeds even on an empty DB:

read-cypher: RETURN 'connected' AS status

Expected:

{ "status": "connected" }

. Any result confirms the server is alive and the credentials are valid.

If the database has data, also run:

get-schema

and confirm it returns the node labels and relationship types you expect.

通过Agent或直接通过MCP运行

get-schema

。不要用“是否返回标签？”作为测试——空数据库不会返回标签，这与连接失败的表现一致。

请改用以下测试——即使是空数据库也会成功：

read-cypher: RETURN 'connected' AS status

预期结果：

{ "status": "connected" }

。任何结果都能确认服务器正常运行且凭证有效。

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

get-schema

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

HTTP Transport

HTTP传输

HTTP transport runs the MCP server as a persistent network service — useful for shared servers, containers, or multiple clients.

bash

undefined

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

bash

undefined

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


Editor config for HTTP (no credentials in config — server holds them):
```json
{
  "mcpServers": {
    "neo4j-http": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

Per-request auth (omit

--neo4j-username

--neo4j-password

from the server command): each client request must include an

Authorization: Basic <base64(username:password)>

header. Generate the value with:

bash

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

Then add to the editor config:

json

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

Security: bind to
127.0.0.1
, not
0.0.0.0
. Only change to a broader interface if you need remote access and have TLS + auth in front of it.

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模式的编辑器配置（配置中不含凭证——由服务器保存）：
```json
{
  "mcpServers": {
    "neo4j-http": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

请求级认证（服务器命令中省略

--neo4j-username

--neo4j-password

）：每个客户端请求必须包含

Authorization: Basic <base64(用户名:密码)>

头。使用以下命令生成该值：

bash

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

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

json

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

安全提示：绑定到
127.0.0.1
，而非
0.0.0.0
。只有在需要远程访问且已配置TLS和认证的情况下，才切换到更广泛的接口。

Environment Variables

环境变量

Variable	Required	Default	Notes
`NEO4J_URI`	yes	—	`neo4j+s://` for Aura; `bolt://` for local
`NEO4J_USERNAME`	yes	—
`NEO4J_PASSWORD`	yes	—
`NEO4J_DATABASE`	no	server default	Specify explicitly to avoid routing to wrong DB
`NEO4J_READ_ONLY`	no	`false`	Set `true` to hide `write-cypher` (safe default for exploration)

When to set
NEO4J_READ_ONLY=false
(or remove the variable): any use case that needs to write data — imports, MERGE, schema changes, GDS write-back. Without write access, the agent will see only three tools (

get-schema

read-cypher

list-gds-procedures

) and

write-cypher

calls will fail.

变量	是否必填	默认值	说明
`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 Requirement

APOC要求

The MCP server uses APOC for schema introspection (

get-schema

). On Aura, APOC is included automatically. On self-managed Neo4j, install the APOC plugin and whitelist it:

undefined

MCP服务器使用APOC进行模式 introspection（

get-schema

）。在Aura中，APOC已自动包含。在自托管Neo4j中，需要安装APOC插件并将其加入白名单：

undefined

neo4j.conf

dbms.security.procedures.unrestricted=apoc.*


Verify: `read-cypher: RETURN apoc.version() AS v` — if this fails, `get-schema` will return incomplete results.

---

dbms.security.procedures.unrestricted=apoc.*


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

---

Troubleshooting

故障排查

Symptom	Likely cause	Fix
Server not listed in editor	Config file path wrong, JSON malformed, or editor not restarted	Validate JSON ( `python3 -m json.tool settings.json` ); confirm correct file for your editor; restart editor
`neo4j-mcp: command not found`	Editor PATH doesn't include the binary location	Use absolute path in `command` : run `which neo4j-mcp` in terminal and paste the result
Server starts then immediately exits	Python not found (pip install) or wrong binary for OS (binary install)	Run the command manually in terminal to see the error: `/full/path/neo4j-mcp --version`
`AuthenticationException`	Wrong credentials	Verify URI + credentials with `cypher-shell` or driver before editing config
`write-cypher` tool missing	`NEO4J_READ_ONLY=true`	Remove or set to `false` if writes are needed
`ServiceUnavailable`	DB not reachable from editor process	Check firewall, VPN, or whether Aura instance is paused
`list-gds-procedures` returns empty	GDS not installed or Aura Free	GDS requires Aura Professional/Enterprise or self-managed with plugin

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

Checklist

检查清单

```
which neo4j-mcp
```
run and absolute path noted — this goes in
```
command
```
, not
```
neo4j-mcp
```
Connectivity verified (
```
RETURN 'connected'
```
) before editing editor config
Credentials not committed to git;
```
.env
```
in
```
.gitignore
```
```
NEO4J_READ_ONLY
```
set intentionally —
```
true
```
for exploration,
```
false
```
/absent for write use cases
```
NEO4J_DATABASE
```
specified explicitly
Correct config file used for the target editor (VS Code uses
```
servers
```
; all others use
```
mcpServers
```
)
Config is valid JSON (validate with
```
python3 -m json.tool <file>
```
before saving)
Editor restarted after config change

Smoke test passed:

read-cypher: RETURN 'connected' AS status

returns a result

APOC available on self-managed:
```
read-cypher: RETURN apoc.version()
```

已运行
```
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()
```
可正常运行

neo4j-mcp-skill

Original

Translation

Neo4j MCP Skill

Neo4j MCP 技能

When to Use

适用场景

When NOT to Use

不适用场景

Available MCP Tools

可用MCP工具

Installation

安装步骤

Step 1 — Install and find the absolute path

步骤1 — 安装并获取绝对路径

Option A: pip (recommended)

选项A：pip（推荐）

Option B: Download binary

选项B：下载二进制文件

https://github.com/neo4j/mcp/releases -- macOS, Linux, Windows binaries

https://github.com/neo4j/mcp/releases -- 提供macOS、Linux、Windows二进制文件

Option C: Docker

选项C：Docker

Step 2 — Prepare credentials

步骤2 — 准备凭证

.env (gitignored)

.env（已加入git忽略）

or bolt://localhost:7687 # local

或 bolt://localhost:7687 # 本地实例

If cypher-shell not available: python3 -c "

如果没有cypher-shell：python3 -c "

from neo4j import GraphDatabase, version

from neo4j import GraphDatabase, version

d = GraphDatabase.driver('$NEO4J_URI', auth=('$NEO4J_USERNAME','$NEO4J_PASSWORD'))

d = GraphDatabase.driver('$NEO4J_URI', auth=('$NEO4J_USERNAME','$NEO4J_PASSWORD'))

d.verify_connectivity(); print('connected'); d.close()"

d.verify_connectivity(); print('connected'); d.close()"

Step 3 — Configure your editor

步骤3 — 配置编辑器

Step 4 — Restart the editor

步骤4 — 重启编辑器

Step 5 — Smoke test

步骤5 — 冒烟测试

HTTP Transport

HTTP传输

With credentials baked in (simpler — server authenticates all clients as the same user)

内置凭证（更简单——服务器将所有客户端认证为同一用户）

Environment Variables

环境变量

APOC Requirement

APOC要求

neo4j.conf

neo4j.conf

Troubleshooting

故障排查

Checklist

检查清单

References

参考资料