AI导哈

Neo4j MCP服务器

一个用于Neo4j数据库与Claude AI集成的模型上下文协议服务器，提供自然语言交互和Cypher查询执行功能。

  • by mcorpening85
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 mcorpening85/neo4j-mcp-server

使用说明

Neo4j MCP服务器

用于Neo4j数据库与Claude AI集成的模型上下文协议（MCP）服务器，针对Render部署进行了优化。

🚀 快速部署以渲染

概述

此MCP服务器使Claude能够使用自然语言与Neo4j图形数据库进行交互。它提供：

  • 模式探索 -了解你的图形结构
  • Cypher查询执行 -运行读写查询
  • 自然语言接口 -询问有关数据的问题
  • HTTP传输 -通过Render部署进行远程访问
  • 内置健康检查 -渲染兼容的健康端点

部署说明

1.在渲染上部署

  1. 首选 渲染仪表板
  2. 点击 新 → Web服务
  3. 连接此GitHub存储库
  4. 渲染将自动检测 render.yaml 配置
  5. 添加这些 所需的环境变量 在渲染仪表板中：
    NEO4J_URI=bolt://your-neo4j-host:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-secure-password
  6. 点击 创建Web服务
  7. 等待部署（首次部署可能需要2-3分钟）

重要提示： 三个必需的环境变量(NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD)必须在渲染仪表板的“环境”选项卡下添加。没有它们，服务将无法启动。

2.验证部署

检查您的服务是否正在运行：

# Health check endpoint
curl https://YOUR-APP-NAME.onrender.com/health
# Should return: OK

# Root endpoint (also returns health status)
curl https://YOUR-APP-NAME.onrender.com/
# Should return: OK

3.连接到克劳德桌面

部署后，您将获得一个URL，如下所示： https://neo4j-mcp-server.onrender.com

将此添加到您的Claude Desktop配置中：

雨衣： ~/Library/Application Support/Claude/claude_desktop_config.json

窗户： %APPDATA%\\Claude\\claude_desktop_config.json

{
  "mcpServers": {
    "neo4j-render": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOUR-APP-NAME.onrender.com/api/mcp/"
      ]
    }
  }
}

⚠️ 关键： URL 必须 以...结束 /api/mcp/ -别忘了后面的斜线！

✅ 对的： https://YOUR-APP-NAME.onrender.com/api/mcp/
❌ 错误： https://YOUR-APP-NAME.onrender.com

重新启动克劳德桌面（Cmd/Ctrl+R）。

配置

所需的环境变量

变量 描述 示例
NEO4J_URI Neo4j连接URI bolt://localhost:7687 或 neo4j+s://xxxxx.databases.neo4j.io
NEO4J_USERNAME Neo4j用户名 neo4j
NEO4J_PASSWORD Neo4j密码 your-password

可选环境变量

变量 描述 默认值
NEO4J_DATABASE 数据库名称 neo4j
NEO4J_READ_ONLY 启用只读模式 false
NEO4J_READ_TIMEOUT 查询超时（秒） 30
NEO4J_MCP_SERVER_ALLOW_ORIGINS CORS起源 *

运作原理

此部署使用Python反向代理包装器(start.py)即：

  1. 在端口8080上运行（外部，面向渲染器）
  2. 在以下地点进行健康检查 /health 和 / 渲染的端点
  3. 将所有MCP请求转发到内部MCP服务器（端口8081）
  4. 为故障排除提供详细的日志记录

该架构确保：

  • ✅ Render的运行状况检查成功（无“501不支持的方法”错误）
  • ✅ MCP服务器在内部端口上正常运行
  • ✅ 所有POST/GET请求均已正确转发
  • ✅ 服务保持健康和运行

地方发展

使用Docker

# Build the image
docker build -t neo4j-mcp-server .

# Run with your Neo4j credentials
docker run -p 8080:8080 \
  -e NEO4J_URI=bolt://your-neo4j:7687 \
  -e NEO4J_USERNAME=neo4j \
  -e NEO4J_PASSWORD=password \
  neo4j-mcp-server

本地测试：

# Health check
curl http://localhost:8080/health

# Test MCP endpoint
curl -X POST http://localhost:8080/api/mcp/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'

# View logs
docker logs <container-id>

直接安装

# Install the package
pip install mcp-neo4j-cypher requests

# Run the wrapper script
export NEO4J_URI=bolt://localhost:7687
export NEO4J_USERNAME=neo4j
export NEO4J_PASSWORD=password

python3 start.py

测试

健康检查

# Simple health check
curl https://YOUR-APP-NAME.onrender.com/health

# Or check the root endpoint
curl https://YOUR-APP-NAME.onrender.com/

两者都应返回200 OK状态。

与克劳德一起测试

连接后，在Claude中尝试以下提示：

  • “我的Neo4j MCP服务器提供了哪些工具？”
  • “显示我的Neo4j数据库的架构”
  • “查找数据库中的所有Person节点”
  • “数据库中有多少个节点？”

渲染免费层笔记

⚠️ 重要提示： 渲染的免费层在15分钟不活动后会下降。

  • 睡眠后第一次请求：~30-60秒
  • 后续请求：快速
  • 健康检查使服务在活动使用期间保持活动状态

解决：

  • 升级到Starter计划（每月7美元），实现永远在线
  • 使用像这样的保活服务 正常运行时间机器人
  • 接受冷启动延迟（仅影响第一个请求）

故障排除

“错误501：不支持的方法（'PST'）”

原因： 缺少您的Claude Desktop配置 /api/mcp/ 在URL的末尾。

解决方案： 更新您的 claude_desktop_config.json:

{
  "mcpServers": {
    "neo4j-render": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOUR-APP-NAME.onrender.com/api/mcp/"
      ]
    }
  }
}

要点：

  • ✅ URL必须以结尾 /api/mcp/
  • ✅ 别忘了后面的斜线
  • ⚠️ 替换 YOUR-APP-NAME 使用您实际的Render应用程序名称

“未检测到开放端口”错误

固定的！ 此存储库现在包含一个反向代理包装器，可以正确处理Render的健康检查。如果您仍然看到此错误：

  1. 确保您已提取更新的最新代码 start.py 和 Dockerfile
  2. 在渲染日志中检查容器是否正在成功构建
  3. 验证 healthCheckPath: /health 在你的 render.yaml
  4. 确保 requests 库已安装（应在Dockerfile中）

服务无法启动

检查渲染日志：

  1. 转到渲染仪表板→ 您的服务→ Logs
  2. 查找错误消息

常见问题：

  • ❌ 缺少环境变量(NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD)
  • ❌ 无法从Render访问Neo4j URI
  • ❌ Neo4j凭据不正确
  • ❌ Neo4j防火墙阻止Render的IP地址

解决：

# Verify your Neo4j connection locally first
python3 -c "
from neo4j import GraphDatabase
driver = GraphDatabase.driver('YOUR_URI', auth=('USERNAME', 'PASSWORD'))
driver.verify_connectivity()
print('✓ Connection successful')
"

克劳德无法连接

# Test the MCP endpoint (should get a response, even if error)
curl -X POST https://YOUR-APP-NAME.onrender.com/api/mcp/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'

# Check service status
curl https://YOUR-APP-NAME.onrender.com/health

首次请求缓慢

在15分钟不活动后，这在Render的空闲层上是正常的。该服务会减速以节省资源，需要30-60秒才能重新启动。

Neo4j连接问题

如果日志显示“建立连接失败”：

  1. 检查Neo4j是否正在运行 并且可访问
  2. 验证URI格式：
    • 当地： bolt://localhost:7687
    • Neo4j光环： neo4j+s://xxxxx.databases.neo4j.io
    • 云实例： bolt://your-host:7687
  3. 白名单渲染IP 在Neo4j防火墙中（适用于Neo4j Aura/Cloud）
  4. 测试连接 从命令行开始

文档

建筑

┌──────────────────────────────────────────┐
│   Render (Docker Container)              │
│  ┌────────────────────────────────────┐  │
│  │  start.py (Reverse Proxy)          │  │
│  │  Port 8080 (External)              │  │
│  │  ├─ /health → 200 OK               │  │
│  │  ├─ / → 200 OK                     │  │
│  │  └─ /api/mcp/* → Forward to 8081  │  │
│  └────────────────────────────────────┘  │
│  ┌────────────────────────────────────┐  │
│  │  mcp-neo4j-cypher                  │  │
│  │  Port 8081 (Internal)              │  │
│  │  └─ /api/mcp/ → MCP Protocol      │  │
│  └────────────────────────────────────┘  │
└──────────────────────────────────────────┘
           │
           ↓
    ┌──────────────┐
    │   Neo4j DB   │
    └──────────────┘

许可证

麻省理工学院

鸣谢

内置：

贡献

欢迎问题和拉取请求！请确保：

  • 健康检查仍然有效
  • 记录环境变量
  • 保持渲染兼容性

相关 MCP