Neo4j MCP Readonly

Neo4j MCP服务器

](https://badge.fury.io/js/neo4j-mcp-readonly)  ](https://nodejs.org/)

一种模型上下文协议（MCP）服务器，提供 只读的 访问您的Neo4j数据库。此服务器允许您将Cursor IDE连接到Neo4j数据库，并使用全面的数据库探索工具运行安全的只读Cypher查询。

🚀 快速开始

安装

# Install globally
npm install -g neo4j-mcp-readonly

# Or use with npx (no installation required)
npx neo4j-mcp-readonly --help

基本用法

# Start with command line arguments
neo4j-mcp-readonly --neo4j-uri bolt://localhost:7687 --neo4j-username neo4j --neo4j-password mypassword

# Or use environment variables
NEO4J_URI=bolt://localhost:7687 NEO4J_USERNAME=neo4j NEO4J_PASSWORD=mypassword neo4j-mcp-readonly

📋 特性

• 🔒 只读查询：仅允许安全读取操作（MATCH、RETURN、WITH、UNIND等）
• 🛡️ 查询验证：自动阻止危险操作，如CREATE、DELETE、SET、MERGE
• 🔍 模式探索：获取数据库架构信息，包括标签、关系和属性
• 📊 数据库统计：节点/关系计数、属性分析等
• 🧪 连接测试：内置连接测试功能
• ⚡ CLI支持：简单的命令行配置
• 🐳 Docker就绪：包括Docker Compose配置示例
• 🔧 灵活的身份验证：支持环境变量和命令行参数

🛠️ 配置方法

方法1：命令行参数

neo4j-mcp-readonly \
  --neo4j-uri bolt://localhost:7687 \
  --neo4j-username neo4j \
  --neo4j-password your_password

方法2：环境变量

export NEO4J_URI=bolt://localhost:7687
export NEO4J_USERNAME=neo4j
export NEO4J_PASSWORD=your_password
neo4j-mcp-readonly

方法3：混合方法

# Environment for sensitive data, CLI for the rest
export NEO4J_PASSWORD=your_secure_password
neo4j-mcp-readonly --neo4j-uri bolt://myserver:7687 --neo4j-username myuser

🎯 使用Cursor IDE

选项1：使用npx（推荐）

将此添加到光标MCP设置中：

{
  "mcpServers": {
    "neo4j": {
      "command": "npx",
      "args": [
        "neo4j-mcp-readonly",
        "--neo4j-uri", "bolt://localhost:7687",
        "--neo4j-username", "neo4j",
        "--neo4j-password", "your_password_here"
      ]
    }
  }
}

选项2：使用环境变量

{
  "mcpServers": {
    "neo4j": {
      "command": "npx",
      "args": ["neo4j-mcp-readonly"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your_password_here"
      }
    }
  }
}

选项3：最小设置（仅限密码）

对于只需要指定密码的简单本地设置：

{
  "mcpServers": {
    "neo4j": {
      "command": "npx",
      "args": ["neo4j-mcp-readonly", "--neo4j-password", "your_password_here"]
    }
  }
}

这假定默认值： bolt://localhost:7687 和用户名 neo4j.

配置步骤

1. 安装软件包 （如果不使用npx）：

   npm install -g neo4j-mcp-readonly

1. 将MCP服务器添加到游标:

- 打开光标IDE - 转到光标设置（Cmd/Ctrl+，） - 搜索“MCP”或转到扩展>MCP - 添加配置（见上面的示例）

1. 重新启动游标 使更改生效

1. 开始查询:

   Can you show me the schema of my Neo4j database?
   How many User nodes do I have?
   Show me sample data for the Movie label

🛠️ 可用工具

核心工具

分析工具

模式分析工具

💡 查询示例

基础数据探索

MATCH (n:Person) RETURN n.name, n.age LIMIT 10

关系分析

MATCH (p:Person)-[r:FRIENDS_WITH]->(f:Person) 
RETURN p.name, f.name, r.since

基于属性的过滤

MATCH (m:Movie) 
WHERE m.year > 2000 
RETURN m.title, m.year 
ORDER BY m.year DESC

🔒 安全功能

允许的操作

• MATCH -图案匹配
• RETURN -返回结果
• WITH -链查询部件
• UNWIND -展开列表
• SHOW -显示数据库元数据
• 只读 CALL 程序（模式、标签等）

受阻操作

• CREATE -创建节点/关系
• DELETE / DETACH DELETE -删除数据
• MERGE -创建或匹配
• SET -设置属性
• REMOVE -删除属性/标签
• DROP -删除索引/约束
• ALTER -正在更改架构
• 大多数 CALL 程序（只读程序除外）

🐳 Docker设置

使用提供的Docker Compose示例：

# Copy the example
cp examples/docker-compose.yml .

# Edit password in docker-compose.yml
# Then start Neo4j
docker-compose up -d

# Connect with MCP server
neo4j-mcp-readonly --neo4j-password your_password_here

🔧 发展

地方发展

git clone https://github.com/ThisIsVoid/neo4j-mcp-readonly.git
cd neo4j-mcp-readonly
npm install
npm run build
npm run dev

建筑

npm run build

测试

# Test connection
neo4j-mcp-readonly --help

# Test with your database
NEO4J_PASSWORD=test neo4j-mcp-readonly

📚 高级配置

自定义Neo4j配置

# Neo4j Aura
neo4j-mcp-readonly \
  --neo4j-uri neo4j+s://xxxx.databases.neo4j.io \
  --neo4j-username neo4j \
  --neo4j-password your_aura_password

# Neo4j Enterprise with custom port
neo4j-mcp-readonly \
  --neo4j-uri bolt://enterprise-server:7687 \
  --neo4j-username readonly_user \
  --neo4j-password readonly_password

# Local Neo4j with custom database
neo4j-mcp-readonly \
  --neo4j-uri bolt://localhost:7687/movies \
  --neo4j-username neo4j \
  --neo4j-password mypassword

环境文件设置

创建一个 .env 文件：

NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_secure_password

然后运行：

source .env
neo4j-mcp-readonly

🚨 故障排除

连接问题

1. 验证Neo4j是否正在运行:

   # Check if Neo4j is listening
   netstat -an | grep 7687

1. 测试直接连接:

   # Use Neo4j's cypher-shell
   cypher-shell -u neo4j -p your_password

1. 检查防火墙/网络:

- 确保端口7687可访问 - 检查是否需要身份验证

配置问题

1. 无效凭证:

   Configuration error:
     neo4j.password: Password is required

解决方案：通过提供密码 --neo4j-password 或 NEO4J_PASSWORD

1. 连接被拒绝:

   Failed to connect to Neo4j: ServiceUnavailable

解决方案：检查URI并确保Neo4j正在运行

MCP问题

1. 在游标中找不到服务器:

- 验证npx是否可以找到该包： npx neo4j-mcp-readonly --help - 检查游标MCP配置语法 - 配置更改后重新启动Cursor

1. 查询被阻止:

   Query contains forbidden operations

解决方案：确保查询只包含允许的读取操作

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

🤝 贡献

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

📊 向NPM发布

向NPM发布 自由 对于开源软件包。以下是如何发布：

首次设置

1. 创建NPM帐户：参观 并注册
2. 本地登录:

   npm login

1. 更新package.json：将存储库URL更改为GitHub存储库

出版

# Build the package
npm run build

# Publish (runs prepublishOnly script automatically)
npm publish

# For beta versions
npm publish --tag beta

更新中

# Update version
npm version patch  # or minor, major

# Publish update
npm publish

🌟 明星历史

如果这个项目对你有帮助，请考虑在GitHub上给它一颗星！

📞 支持

• 🐛 错误报告:
• 💬 讨论:
• 📖 文档：此README和内联代码注释
• 🎯 例子：检查 /examples 目录

______________________________________________________________________

由以下材料制成❤️ Neo4j和Cursor社区