Neo4j MCP Server for Cursor

这是一个Cursor MCP（模型上下文协议）服务器，它能够无缝地与Neo4j数据库进行交互。

功能

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

先决条件

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

使用Docker Compose运行Neo4j

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

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

2. 使用Docker Compose启动Neo4j：

   docker-compose up -d
   

3. 访问Neo4j浏览器：http://localhost:7474

   • 默认用户名：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自身启动。不过，您可以手动测试它：

# 直接运行
bun run index.ts

# 使用提供的脚本运行并记录日志
./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 - 错误处理的实用函数

构建用于生产

为了构建用于生产的服务器：

# 构建服务器
bun build index.ts --outdir ./dist

# 设置输出文件为可执行
chmod +x ./dist/index.js

构建过程将所有依赖项捆绑到一个JavaScript文件中，使得分发和运行服务器变得容易，无需安装依赖项。

运行服务器

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

./run-mcp-server.sh

此脚本：

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

注意：此脚本需要Bun已安装并在您的PATH中可用。

许可证

MIT