Neo4j MCP

一个模型上下文协议 (MCP) 服务器，允许 Claude（以及其他 MCP 客户端）查询和修改 Neo4j 图数据库。它既可以作为独立的 MCP 服务器，也可以作为** Claude Code 插件**使用，安装一次即可在任何项目中重复使用。

每个项目通过本地 .env 文件提供其自己的 Neo4j 凭据，因此同一个插件可以根据打开 Claude Code 的文件夹不同而指向不同的数据库。

功能特性

• 一个统一的 cypher_query 工具，具有明确的 read / write 模式。

• 架构内省：标签、关系类型和属性键。

• 完整的结果序列化 — 保留节点/关系的 element_id、标签、类型以及 Neo4j 时间/空间值。

• 带有截断标志的结果大小限制，防止失控的 MATCH (n) 导致响应过大。

• 通过 .env 实现项目级凭据管理（由工作目录中的 python-dotenv 加载）。

• 支持 stdio（Claude Code、Claude Desktop、Cursor）和 SSE。

Related MCP server: neo4j-server-remote

先决条件

• Python 3.10+

• 可访问的 Neo4j 数据库（本地、Docker 或 Aura）

• pip（或 uv、pipx）

安装 Python 包

该插件调用名为 neo4j-mcp-server 的控制台脚本，因此该包必须首先位于您的 PATH 中。

git clone https://github.com/your-repo/neo4j-mcp.git
cd neo4j-mcp
pip install -e .

验证安装是否成功：

which neo4j-mcp-server
neo4j-mcp-server --help

提示：如果您使用 pipx，pipx install -e . 可以将服务器与您的全局 Python 环境隔离开来。

作为 Claude Code 插件使用

该仓库在 .claude-plugin/plugin.json 中提供了一个插件清单。一旦在用户级别安装，neo4j MCP 服务器将在每个 Claude Code 会话和任何项目中可用。

1. 安装插件

在 Claude Code 内部执行：

/plugin install /absolute/path/to/neo4j-mcp

这将全局注册该清单。（如果您发布了插件，也可以通过市场添加它 — 请参阅 Claude Code 的插件文档。）

2. 在任何需要连接 Neo4j 的项目中放入 .env 文件

MCP 服务器继承了 Claude Code 的工作目录，因此 python-dotenv 会读取该项目根目录下的 .env 文件。不同的文件夹对应不同的数据库，无需重新配置插件。

# my-project/.env
NEO4J_HOST=localhost
NEO4J_PORT=7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-secret
NEO4J_DATABASE=neo4j

对于 Aura / 加密连接：

NEO4J_HOST=xxx.databases.neo4j.io
NEO4J_PORT=7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-aura-password
NEO4J_URI_SCHEME=neo4j+s
NEO4J_ENCRYPTED=true

对于未经身份验证的本地实例，请将 NEO4J_USERNAME 和 NEO4J_PASSWORD 留空。

不要提交 .env 文件。 请将其添加到每个项目的 .gitignore 中。

3. 在 Claude Code 中使用

打开项目，然后向 Claude 提问，例如：

• “此图中存在哪些标签和关系类型？”

• “查找连接数最多的 10 个 Person 节点。”

• “创建一个标题为 Inception 且于 2010 年发行的 Movie 节点。”

Claude 将根据需要调用 cypher_query、get_database_schema 和 test_database_connection 工具。

在没有 Claude Code 的情况下使用

同一个包可以作为任何兼容 MCP 的客户端的普通 MCP 服务器使用。

Claude Desktop / Cursor

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或您的 Cursor MCP 配置中：

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

通过在客户端启动进程的位置旁边放置 .env 文件，或者在环境变量块中导出 NEO4J_* 变量来设置凭据。

SSE 传输（Web 客户端）

neo4j-mcp-server --transport sse --host 0.0.0.0 --port 3000

独立 CLI

捆绑了一个小型客户端用于一次性测试：

neo4j-mcp-client --test
neo4j-mcp-client --schema
neo4j-mcp-client --query "MATCH (n) RETURN count(n) AS nodes"
neo4j-mcp-client --write --query "CREATE (p:Person {name: 'Alice'}) RETURN p"

配置参考

所有设置均从环境变量（或工作目录中的 .env 文件）读取。

MCP 服务器暴露的工具

资源：neo4j://schema，neo4j://connection。提示：cypher_query_help。

开发

pip install -e ".[dev]"
pytest                    # 21 unit tests, no live database needed
ruff check src/ tests/
mypy src/neo4j_mcp/

故障排除

• Neo4j authentication failed — 用户名/密码不匹配。对于未经身份验证的数据库，请将两者都留空（不要将其设置为 neo4j/neo4j）。

• Neo4j service unavailable — 数据库已关闭或 NEO4J_HOST / NEO4J_PORT 设置错误。尝试使用 cypher-shell -a bolt://$NEO4J_HOST:$NEO4J_PORT 进行确认。

• 插件找不到 neo4j-mcp-server — 控制台脚本不在 Claude Code 继承的 PATH 中。请使用 pipx 安装，或确保您的 shell rc 文件为 GUI 应用程序导出了正确的 PATH。在 macOS 上，GUI 应用程序不会读取 ~/.zshrc；请使用 launchctl setenv PATH ... 或安装到 /usr/local/bin。

• 读取时出现 truncated: true — 增加调用中的 limit 参数，或在 .env 中调高 NEO4J_DEFAULT_RESULT_LIMIT。

MIT 许可。