mcp-neo4j-cypher

🔍⁉️ Neo4j MCP 服务

mcp-name: io.github.neo4j-contrib/mcp-neo4j-cypher

🌟 概述

一种模型上下文协议（MCP）服务实现，可通过 Neo4j 提供数据库交互和图探索功能。此服务支持运行 Cypher 图查询、分析复杂领域数据，并自动生成业务洞察，还可以结合应用的分析工具进一步增强这些洞察。

此 MCP 服务支持如下所述的 Text2Cypher 工作流。

• 蓝色步骤由 Agent 处理
• 紫色步骤由 Cypher 或其他 MCP 服务处理
• 绿色步骤由用户处理

用户问题作为输入进入流程，输出则是 Agent 生成的答案。

📋 前提条件

• Neo4j 数据库：正在运行的 Neo4j 实例（Aura 或自托管）
• APOC 插件：必须在 Neo4j 实例上安装并启用 APOC 插件。get_neo4j_schema 工具需要此插件才能正常运行。

🧩 组件

🛠️ 工具

此服务提供以下核心工具：

📊 查询工具

• read_neo4j_cypher

  • 执行 Cypher 只读查询，从数据库读取数据
  • 输入：
    • query（字符串）：要执行的 Cypher 查询
    • params（字典，可选）：要传递给 Cypher 查询的参数
  • 返回：以 JSON 序列化的对象数组形式返回查询结果
  • 超时：只读查询受可配置的超时限制（默认：30 秒），以避免长时间运行的查询打断对话流程

• write_neo4j_cypher

  • 执行会更新数据的 Cypher 查询
  • 输入：
    • query（字符串）：要执行的 Cypher 更新查询
    • params（字典，可选）：要传递给 Cypher 查询的参数
  • 返回：以 JSON 序列化的结果摘要计数器，格式为 { nodes_updated: number, relationships_created: number, ... }
  • 可用性：可通过提供 --read-only CLI 标志或设置 NEO4J_READ_ONLY=true 环境变量来禁用

🕸️ 架构工具

• get_neo4j_schema
  • 获取图数据库中所有节点类型的列表，以及它们的属性名称、类型和与其他节点类型的关系
  • 要求：必须安装并启用 APOC 插件。
  • 输入：
    • sample_param（整数，可选）：用于架构分析的节点采样数量。提供此参数时会覆盖服务默认值。
  • 返回：以 JSON 序列化的节点标签列表，包含两个字典：一个用于属性，一个用于关系
  • 性能：默认使用采样（每个标签采样 1000 个节点）。在大型数据库中，减少采样数量可以加快分析。若要停止采样，请设为 -1。

🏷️ 命名空间

此服务支持命名空间，以便同时使用多个 Neo4j MCP 服务。提供命名空间时，所有工具名称都会加上该命名空间作为前缀，并以连字符分隔（例如，mydb-read_neo4j_cypher）。

当您需要在同一会话中连接到多个 Neo4j 数据库或实例时，此功能非常有用。

⚙️ 查询配置

此服务提供配置选项，用于优化查询性能和管理响应大小：

⏱️ 查询超时

配置只读查询的超时时间，以避免长时间运行的查询打断对话流程：

命令行：

mcp-neo4j-cypher --read-timeout 60  # 60 seconds

环境变量：

export NEO4J_READ_TIMEOUT=60

Docker：

docker run -e NEO4J_READ_TIMEOUT=60 mcp-neo4j-cypher:latest

默认值：30 秒。超过此超时时间的只读查询将自动取消，以确保与 AI 模型的交互保持响应迅速。

📏 令牌限制

控制查询响应的最大大小，避免超出 AI 模型的处理能力：

命令行：

mcp-neo4j-cypher --token-limit 4000

环境变量：

export NEO4J_RESPONSE_TOKEN_LIMIT=4000

Docker：

docker run -e NEO4J_RESPONSE_TOKEN_LIMIT=4000 mcp-neo4j-cypher:latest

当响应超出令牌限制时，系统会使用 tiktoken 自动截断响应，使其符合指定限制。这样可以确保：

• 性能一致：响应不会超出模型上下文限制
• 控制成本：避免 AI 交互中使用过多令牌
• 可靠性：大型数据集不会打断对话流程

注意：令牌限制仅适用于 read_neo4j_cypher 响应。架构查询和写入操作会返回摘要信息，不受此限制影响。

🔍 架构采样

使用 get_neo4j_schema 工具的 sample 参数，控制架构检查的性能和范围：

命令行：

mcp-neo4j-cypher --sample 1000  # Sample 1000 nodes per label

环境变量：

export NEO4J_SCHEMA_SAMPLE_SIZE=1000

Docker：

docker run -e NEO4J_SCHEMA_SAMPLE_SIZE=1000 mcp-neo4j-cypher:latest

sample 参数控制生成数据库架构时要检查的节点数量：

• 默认值：每个标签采样 1000 个节点进行架构分析
• 性能：较低的值（100、500）可加快大型数据库的架构检查
• 准确性：较高的值（5000、10000）可更全面地覆盖架构
• 全量扫描：设置为 -1 可检查所有节点（大型数据库可能会非常慢）
• 单次调用覆盖：get_neo4j_schema 工具接受 sample_param 参数，可覆盖服务默认值

采样机制（通过 APOC 的 apoc.meta.schema）：

• 对每个节点标签，计算跳过数量：totalNodesForLabel / sample ± 10%
• 根据跳过数量，每隔 N 个节点检查一次
• sample 值越高，检查的节点越多
• 由于采用随机采样，每次运行的结果可能不同

示例场景：

# Fast schema inspection for large databases
export NEO4J_SCHEMA_SAMPLE_SIZE=100

# Balanced performance and accuracy (default)
export NEO4J_SCHEMA_SAMPLE_SIZE=1000

# Comprehensive schema analysis
export NEO4J_SCHEMA_SAMPLE_SIZE=5000

# Full database scan (use with caution on large databases)
export NEO4J_SCHEMA_SAMPLE_SIZE=-1

性能注意事项：

• 大型数据库：使用较低的采样值（100-500）以避免超时
• 开发环境：使用较高的采样值（1000-5000）以全面了解架构
• 生产环境：根据使用场景，在性能和架构完整性之间取得平衡

🏗️ 本地开发与部署

🐳 本地 Docker 开发

在本地构建并运行，以进行测试或远程部署：

# Build the Docker image with a custom name from your local version of the server
docker build -t mcp-neo4j-cypher:latest .

# Run locally (uses http transport by default for Docker)
docker run -p 8000:8000 \
  -e NEO4J_URI="bolt://host.docker.internal:7687" \
  -e NEO4J_USERNAME="neo4j" \
  -e NEO4J_PASSWORD="your-password" \
  mcp-neo4j-cypher:latest

# Access the server at http://localhost:8000/mcp/

🚀 传输模式

根据部署方式，服务支持不同的传输协议：

• STDIO（用于本地开发）：为 Claude Desktop 和本地工具提供标准输入/输出
• HTTP（用于远程部署）：为 Web 部署和微服务提供 RESTful HTTP
• SSE：为旧版 Web 部署提供服务器发送事件

根据使用场景选择传输方式：

• 本地开发/Claude Desktop：使用 stdio
• 远程部署：使用 http
• 旧版 Web 客户端：使用 sse

🔒 安全防护

该服务包含全面的安全防护，采用安全默认配置，可防范常见的基于 Web 的攻击，同时在使用 HTTP 传输时保留完整的 MCP 功能。

🛡️ DNS 重绑定防护

TrustedHost 中间件会验证 Host 标头，以防止 DNS 重绑定攻击：

默认安全配置：

• 默认仅允许 localhost 和 127.0.0.1 主机
• 恶意网站无法诱骗浏览器访问你的本地服务

环境变量：

export NEO4J_MCP_SERVER_ALLOWED_HOSTS="example.com,www.example.com"

🌐 CORS 防护

**跨源资源共享（CORS）**防护默认会阻止基于浏览器的请求：

环境变量：

export NEO4J_MCP_SERVER_ALLOW_ORIGINS="https://example.com,https://example.com"

🔧 完整安全配置

开发环境配置：

mcp-neo4j-cypher --transport http \
  --allowed-hosts "localhost,127.0.0.1" \
  --allow-origins "http://localhost:3000"

生产环境配置：

mcp-neo4j-cypher --transport http \
  --allowed-hosts "example.com,www.example.com" \
  --allow-origins "https://example.com,https://example.com"

🚨 安全最佳实践

对于 allow_origins：

• 指定具体来源：["https://example.com", "https://example.com"]
• 在生产环境中使用凭据时，绝不要使用 "*"
• 在生产环境中使用 HTTPS 来源

对于 allowed_hosts：

• 添加你的实际域名：["example.com", "www.example.com"]
• 仅在开发环境中添加 localhost
• 除非你了解其中的风险，否则绝不要使用 "*"

🔧 在 Claude Desktop 中使用

使用 DXT

从 发布页面下载最新的 .dxt 文件，并使用你的 MCP 客户端安装。

💾 已发布的软件包

可在 PyPi 上找到：https://pypi.org/project/mcp-neo4j-cypher/

通过环境变量配置数据库连接，将此服务添加到你的 claude_desktop_config.json 中。你也可以通过 CLI 参数或环境变量指定传输方式、命名空间和其他配置变量。

{
  "mcpServers": {
    "neo4j-database": {
      "command": "uvx",
      "args": [ "[email protected]", "--transport", "stdio"  ],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "<your-password>",
        "NEO4J_DATABASE": "neo4j"
      }
    }
  }
}

🌐 HTTP 传输配置

使用安全中间件进行自定义 HTTP 配置：

# Complete HTTP configuration with security
mcp-neo4j-cypher --transport http \
  --server-host 127.0.0.1 \
  --server-port 8080 \
  --server-path /mcp/ \
  --allowed-hosts "localhost,127.0.0.1,example.com" \
  --allow-origins "https://yourapp.com"

# Using environment variables
export NEO4J_TRANSPORT=http
export NEO4J_MCP_SERVER_HOST=127.0.0.1
export NEO4J_MCP_SERVER_PORT=8080
export NEO4J_MCP_SERVER_PATH=/mcp/
export NEO4J_MCP_SERVER_ALLOWED_HOSTS="localhost,127.0.0.1,example.com"
export NEO4J_MCP_SERVER_ALLOW_ORIGINS="https://yourapp.com"
mcp-neo4j-cypher

多数据库示例

以下示例展示了如何使用命名空间连接多个 Neo4j 数据库：

{
  "mcpServers": {
    "movies-neo4j": {
      "command": "uvx",
      "args": ["[email protected]", "--namespace", "movies"],
      "env": {
        "NEO4J_URI": "neo4j+s://demo.neo4jlabs.com",
        "NEO4J_USERNAME": "recommendations",
        "NEO4J_PASSWORD": "recommendations",
        "NEO4J_DATABASE": "recommendations"
      }
    },
    "local-neo4j": {
      "command": "uvx",
      "args": ["[email protected]"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "password",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_NAMESPACE": "local"
      }
    }
  }
}

在此配置中：

• movies 数据库的工具会添加 movies- 前缀（例如，movies-read_neo4j_cypher）
• local 数据库的工具会添加 local- 前缀（例如，local-get_neo4j_schema）

仍支持使用 --db-url、--username、--password、--read-timeout 和其他命令行参数的语法，但更推荐使用环境变量：

"mcpServers": {
  "neo4j": {
    "command": "uvx",
    "args": [
      "[email protected]",
      "--db-url",
      "bolt://localhost",
      "--username",
      "neo4j",
      "--password",
      "<your-password>",
      "--namespace",
      "mydb",
      "--transport",
      "sse",
      "--server-host",
      "127.0.0.1",
      "--server-port",
      "8000"
      "--server-path",
      "/mcp/"
    ]
  }
}

🐳 使用 Docker

此处使用 Docker Hub 托管的 Cypher MCP 服务镜像，并通过 stdio 传输与 Claude Desktop 配合使用。

配置详情：

• -i：交互模式——保持 STDIN 打开，以便通过 stdio 传输进行通信
• --rm：容器退出时自动移除（清理）
• -p 8000:8000：端口映射——将主机端口 8000 映射到容器端口 8000
• NEO4J_TRANSPORT=stdio：使用 stdio 传输以兼容 Claude Desktop
• NEO4J_NAMESPACE=neo4j：为工具添加 "neo4j-" 前缀（例如，neo4j-read_neo4j_cypher）
• NEO4J_URI=bolt://host.docker.internal:7687：允许 Docker 容器连接到运行在主机上的 Neo4j

{
  "mcpServers": {
    "neo4j": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p", 
        "8000:8000",
        "-e", "NEO4J_URI=bolt://host.docker.internal:7687",
        "-e", "NEO4J_USERNAME=neo4j",
        "-e", "NEO4J_PASSWORD=password",
        "-e", "NEO4J_NAMESPACE=neo4j",
        "-e", "NEO4J_TRANSPORT=stdio",
        "mcp/neo4j-cypher:latest"
      ]
    }
  }
}

🐳 Docker 部署

Neo4j MCP 服务可使用 Docker 部署，以便远程部署。Docker 部署应使用 HTTP 传输，以支持 Web 访问。若要将此部署与 Claude Desktop 等应用程序集成，你需要在 MCP 配置中使用代理，例如 mcp-remote。

📦 使用你构建的镜像

使用 docker build -t mcp-neo4j-cypher:latest . 在本地构建后：

# Run with http transport (default for Docker)
docker run --rm -p 8000:8000 \
  -e NEO4J_URI="bolt://host.docker.internal:7687" \
  -e NEO4J_USERNAME="neo4j" \
  -e NEO4J_PASSWORD="password" \
  -e NEO4J_DATABASE="neo4j" \
  -e NEO4J_TRANSPORT="http" \
  -e NEO4J_MCP_SERVER_HOST="0.0.0.0" \
  -e NEO4J_MCP_SERVER_PORT="8000" \
  -e NEO4J_MCP_SERVER_PATH="/mcp/" \
  mcp/neo4j-cypher:latest

# Run with security middleware for production
docker run --rm -p 8000:8000 \
  -e NEO4J_URI="bolt://host.docker.internal:7687" \
  -e NEO4J_USERNAME="neo4j" \
  -e NEO4J_PASSWORD="password" \
  -e NEO4J_DATABASE="neo4j" \
  -e NEO4J_TRANSPORT="http" \
  -e NEO4J_MCP_SERVER_HOST="0.0.0.0" \
  -e NEO4J_MCP_SERVER_PORT="8000" \
  -e NEO4J_MCP_SERVER_PATH="/mcp/" \
  -e NEO4J_MCP_SERVER_ALLOWED_HOSTS="example.com,www.example.com" \
  -e NEO4J_MCP_SERVER_ALLOW_ORIGINS="https://example.com" \
  mcp/neo4j-cypher:latest

🔧 环境变量

🌐 面向旧版 Web 访问的 SSE 传输

使用 SSE 传输（面向旧版 Web 客户端）时，服务会公开一个 HTTP 端点：

# Start the server with SSE transport
docker run -d -p 8000:8000 \
  -e NEO4J_URI="neo4j+s://demo.neo4jlabs.com" \
  -e NEO4J_USERNAME="recommendations" \
  -e NEO4J_PASSWORD="recommendations" \
  -e NEO4J_DATABASE="recommendations" \
  -e NEO4J_TRANSPORT="sse" \
  -e NEO4J_MCP_SERVER_HOST="0.0.0.0" \
  -e NEO4J_MCP_SERVER_PORT="8000" \
  --name neo4j-mcp-server \
  mcp-neo4j-cypher:latest

# Test the SSE endpoint
curl http://localhost:8000/sse

# Use with MCP Inspector
npx @modelcontextprotocol/inspector http://localhost:8000/sse

🐳 Docker Compose

对于更复杂的部署，可以使用 Docker Compose：

version: '3.8'

services:
  # Deploy Neo4j Database (optional)
  neo4j:
    image: neo4j:5.26.1 # or another version
    environment:
      - NEO4J_AUTH=neo4j/password
      - NEO4J_PLUGINS=["apoc"]
    ports:
      - '7474:7474' # HTTP
      - '7687:7687' # Bolt
    volumes:
      - neo4j_data:/data

  # Deploy Cypher MCP Server
  mcp-neo4j-cypher-server:
    image: mcp/neo4j-cypher:latest
    ports:
      - '8000:8000'
    environment:
      - NEO4J_URI=bolt://host.docker.internal:7687
      - NEO4J_USERNAME=neo4j
      - NEO4J_PASSWORD=password
      - NEO4J_DATABASE=neo4j
      - NEO4J_TRANSPORT=http
      - NEO4J_MCP_SERVER_HOST=0.0.0.0 # must be 0.0.0.0 for sse  or http transport in Docker
      - NEO4J_MCP_SERVER_PORT=8000
      - NEO4J_MCP_SERVER_PATH=/mcp/
      - NEO4J_NAMESPACE=local
    depends_on:
      - neo4j

volumes:
  neo4j_data:

运行命令：docker-compose up -d

🔗 使用 Docker 集成 Claude Desktop

要让 Claude Desktop 通过 http 传输连接 Docker 化的服务：

{
  "mcpServers": {
    "neo4j-docker": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "http://localhost:8000/mcp/"]
    }
  }
}

注意：先以 HTTP 传输方式启动 Docker 容器，然后 Claude Desktop 就可以通过 HTTP 端点和代理服务（例如 mcp-remote）连接到它。

🚀 开发

📦 先决条件

1. 安装 uv：

# Using pip
pip install uv

# Using Homebrew on macOS
brew install uv

# Using cargo (Rust package manager)
cargo install uv

2. 克隆仓库并设置开发环境：

# Clone the repository
git clone https://github.com/neo4j-contrib/mcp-neo4j.git
cd mcp-neo4j-cypher

# Create and activate virtual environment using uv
uv venv
source .venv/bin/activate  # On Unix/macOS
.venv\Scripts\activate     # On Windows

# Install dependencies including dev dependencies
uv pip install -e ".[dev]"

3. 运行集成测试

./tests.sh

🔧 开发配置

使用本地源代码通过 Claude Desktop 进行开发：

{
  "mcpServers": {
    "neo4j-dev": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-neo4j-cypher", "run", "mcp-neo4j-cypher", "--transport", "stdio", "--namespace", "dev"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "<your-password>",
        "NEO4J_DATABASE": "neo4j"
      }
    }
  }
}

将 /path/to/mcp-neo4j-cypher 替换为实际的项目目录路径。

📄 许可证

此 MCP 服务采用 MIT 许可证。这意味着你可以自由使用、修改和分发此软件，但须遵守 MIT 许可证的条款和条件。详情请参阅项目仓库中的 LICENSE 文件。