Neo4j MCP Server for Cursor

用于 Cursor 的 Neo4j MCP 服务

一个 Cursor MCP（模型上下文协议）服务，可在 Cursor IDE 中直接与 Neo4j 数据库无缝交互。

功能

• 连接 Neo4j 数据库
• 执行 Cypher 查询并获取结果
• 将 Neo4j 专用数据类型转换为标准 JavaScript 对象
• 使用官方 MCP SDK 和 stdio 传输方式，与 Cursor 无缝集成
• 支持使用环境变量安全管理凭据
• 获取详细的数据库信息和指标
• 监控连接状态和诊断信息

前置条件

• Bun（v1.0.0 或更高版本）
• Neo4j 数据库（本地或远程）

使用 Docker Compose 运行 Neo4j

此项目包含 Docker Compose 配置，可轻松在容器中运行 Neo4j：

1. 确保已安装 Docker 和 Docker Compose。

2. 使用 Docker Compose 启动 Neo4j：

   docker-compose up -d
   

3. 在 http://localhost:7474 访问 Neo4j Browser

   • 默认用户名：neo4j
   • 默认密码：your_password（如 docker-compose.yml 中所指定）

4. 停止 Neo4j：

   docker-compose down
   

5. 停止 Neo4j 并移除所有数据：

   docker-compose down -v
   

注意：docker-compose.yml 中的默认密码设置为 your_password。用于生产环境时，请将其更改为安全密码，并相应更新 .env 文件。

安装

1. 克隆此代码库：

   git clone https://github.com/yourusername/neo4j-mcp.git
   cd neo4j-mcp
   

2. 安装依赖：

   bun install
   

3. 配置环境变量： 在根目录中创建 .env 文件，并填入 Neo4j 凭据：

   NEO4J_URI=neo4j://localhost:7687
   NEO4J_USERNAME=neo4j
   NEO4J_PASSWORD=your_password
   NEO4J_DATABASE=neo4j
   NODE_ENV=development
   

使用

启动服务

此服务使用 stdio 传输方式与 Cursor 通信，因此应由 Cursor 自行启动。不过，你也可以手动测试：

# Run directly
bun run index.ts

# Run with logging using the provided script
./run-mcp-server.sh

可用工具

MCP 服务提供以下工具：

1. 使用明确的凭据连接 Neo4j

使用提供的凭据连接 Neo4j 数据库。

参数：

• uri：Neo4j 数据库 URI（例如 neo4j://localhost:7687）
• username：Neo4j 数据库用户名
• password：Neo4j 数据库密码
• database：（可选）Neo4j 数据库名称

2. 使用环境变量连接 Neo4j

使用环境变量中的凭据连接 Neo4j 数据库。

无需参数。

3. 执行 Cypher 查询

在已连接的 Neo4j 数据库中执行 Cypher 查询。

参数：

• query：要执行的 Cypher 查询
• params：（可选）查询参数

4. 获取数据库信息

获取有关已连接 Neo4j 数据库的详细信息，包括：

• Neo4j 版本和版本类型
• 数据库名称
• 节点和关系数量
• 可用标签
• 关系类型

无需参数。

5. 获取连接状态

获取当前连接状态，包括：

• 连接状态（已连接/已断开）
• 连接详情（URI、数据库）
• 连接时间
• 最近一次错误（如果有）

无需参数。

6. 断开与 Neo4j 的连接

断开与 Neo4j 数据库的连接。

无需参数。

环境变量

可在 .env 文件中设置以下环境变量：

变量	描述	默认值
NEO4J_URI	Neo4j 数据库 URI	neo4j://localhost:7687
NEO4J_USERNAME	Neo4j 数据库用户名	neo4j
NEO4J_PASSWORD	Neo4j 数据库密码	（空）
NEO4J_DATABASE	Neo4j 数据库名称	（默认数据库）
NODE_ENV	环境（开发/生产）	development

与 Cursor 集成

此 MCP 服务专为与 Cursor 的 MCP 集成功能配合使用而设计。Cursor 会自动检测并使用此服务提供的工具。

开发

项目结构

• index.ts - 启动 MCP 服务的入口点
• src/mcpNeo4jServer.ts - 使用 MCP SDK 实现的 MCP 服务
• src/services/neo4jService.ts - 用于数据库操作的 Neo4j 服务
• src/types/index.ts - TypeScript 类型定义
• src/utils/errorHandler.ts - 错误处理工具函数

构建生产版本

要构建生产版本的服务：

# Build the server
bun build index.ts --outdir ./dist

# Make the output file executable
chmod +x ./dist/index.js

构建过程会将所有依赖打包到单个 JavaScript 文件中，便于分发和运行服务，无需安装依赖。

运行服务

你可以使用提供的 shell 脚本运行服务：

./run-mcp-server.sh

此脚本将：

• 将工作目录设置为脚本所在位置
• 如果日志目录不存在，则创建该目录
• 使用 Bun 运行服务，并将输出记录到 logs/mcp-server.log

注意：此脚本要求已安装 Bun，并且 Bun 位于 PATH 中。

许可证

MIT