mcp-neo4j

场景切入：你是否遇到过这样的困境？

你正在开发一个知识图谱问答系统，面对一张包含数十万节点的 Neo4j 图数据库，想要查询「购买过某类商品的用户，在最近三个月内还浏览了哪些相关品类」这种多层关联的复杂问题。手写 Cypher 查询语句不仅费时，还容易出错。这时，如果能直接用自然语言向 AI 提问，让它自动生成并执行 Cypher 查询——这正是 mcp-neo4j 想要解决的问题。

---

背景：Neo4j Labs 与 MCP 协议的碰撞

mcp-neo4j 是 Neo4j Labs 计划下的官方 MCP（Model Context Protocol）服务器集合，由 Neo4j 现场 GenAI 团队开发和维护。

Model Context Protocol 是 Anthropic 在 2024 年底提出的标准化协议，旨在解决 LLM 与外部工具/数据源之间的上下文管理问题。与传统的 Function Calling 不同，MCP 定义了一套统一的通信规范，让 AI 模型可以以一种标准化的方式调用外部工具、读写数据。Neo4j 作为图数据库领域的领导者，率先将这一协议引入图数据库生态，让所有主流 MCP 客户端（Claude Desktop、VS Code、Cursor、Windsurf、 Gemini CLI）都可以直接用自然语言操控 Neo4j。

这个仓库虽然标注为「Labs」项目（实验性质，不享受官方产品 SLA），但更新非常活跃——已累积 345 次提交、56 个版本标签、251 次 Fork，显示出强劲的社区参与度。

---

技术架构：四个独立 MCP Server 的协同生态

该项目采用 Nx monorepo 结构，在 servers/ 目录下管理四个独立的 MCP 服务器，每个服务针对不同场景：

图1：mcp-neo4j-cypher 自然语言转 Cypher 查询的工作流程

mcp-neo4j-cypher — 自然语言转 Cypher 查询引擎

这是最核心的服务器。它基于 fastmcp>=2.10.5 框架构建，使用 neo4j Python 驱动（>=5.26.0）连接数据库，并依赖 tiktoken 对查询结果进行 token 限制控制。

其工作流程如下：AI 模型接收用户的自然语言查询请求后，通过 MCP 协议调用 get_neo4j_schema 工具获取图数据库的 schema 信息（包括节点、属性类型、索引），随后基于 schema 生成 Cypher 查询语句，最后调用 execute_cypher_query 工具执行查询。

为防止误操作，该服务提供了 --read-only 参数，启用后仅允许只读查询。它还内置了 EXPLAIN 查询类型检测，自动判断当前语句为读、写或读写混合操作，从而在只读模式下拒绝写操作。

核心源码约 280 行 Python 代码（server.py），采用异步设计（async/await），通过 FastMCP 装饰器注册工具，支持三种传输模式：

• STDIO（默认）：适用于本地 CLI 工具和 Claude Desktop
• SSE：Server-Sent Events，适用于 Web 场景
• HTTP：Streamable HTTP，适用于现代微服务架构和云原生部署

---

mcp-neo4j-memory — 跨会话知识图谱记忆系统

这个服务器将 Neo4j 用作 AI 的长期记忆存储。它允许 AI 在不同会话、不同客户端之间持久化存储和检索实体与关系。打个比方，就像给 AI 装上了一个「记忆宫殿」——每次对话中学习到的关键信息都可以被存入图数据库，下次对话时再调用出来。

该服务使用 Starlette 作为 Web 框架（非异步方式），通过 pydantic 进行数据建模，确保记忆存储的结构化与可验证性。

---

mcp-neo4j-cloud-aura-api — Neo4j Aura 云服务管理

这个服务器将 Neo4j Aura 云平台的管理 API 暴露为 MCP 工具，AI 可以直接帮你创建/销毁云实例、查看实例列表、按名称搜索、按需扩缩容，以及开启/关闭特定功能。想象一下，用「帮我新建一个 4GB 内存、开启了图数据科学插件的 Aura Professional 实例」这样的自然语言指令来管理你的云数据库。

它使用 requests 而非 neo4j 驱动，因为连接的是 Aura 的管理 API 而非数据库本身。

---

mcp-neo4j-data-modeling — 交互式图数据建模与可视化

这是最有趣的一个服务器。它提供创建、验证和可视化 Neo4j 图数据模型的能力，支持从 Arrows.app 导入/导出数据模型。使用 RDFLib 进行语义图处理，可以自动校验数据模型的完整性与一致性。对数据架构师来说，这是一个用自然语言「对话式建模」的工具。

---

容器化与云部署：开箱即用的生产就绪方案

每个服务器均提供官方 Dockerfile（基于 python:3.13.8-slim）和 docker-compose.yml 文件，可以一键拉起完整环境。以 mcp-neo4j-cypher 的 docker-compose 为例，只需指定 bolt://host.docker.internal:7687 连接宿主机的 Neo4j，即可完成本地开发环境的搭建。

README-Cloud.md 提供了详尽的云部署指南，覆盖 AWS ECS Fargate 和 Azure Container Apps 两大平台。HTTP transport 模式特别针对云原生场景设计，支持自动扩缩容和负载均衡。建议的 ECS Fargate 资源配置为 256 CPU / 512 MB 内存，轻量级部署完全够用。

---

上手体验与适用场景

对于普通 AI 爱好者来说，最大的门槛是需要一个可用的 Neo4j 实例（本地或 Aura 云）。如果你已有 Neo4j 环境，只需安装 MCP 客户端（如 Claude Desktop），配置对应的 MCP server 路径即可。整个配置过程约 10 分钟。

对于开发者而言，四个服务器各有明确的使用场景：

• 想让 AI 帮你写 Cypher → 用 mcp-neo4j-cypher
• 想让 AI 记住跨会话信息 → 用 mcp-neo4j-memory
• 想用自然语言管理 Aura 云实例 → 用 mcp-neo4j-cloud-aura-api
• 想做图数据建模验证 → 用 mcp-neo4j-data-modeling

所有服务器均支持多语言环境变量配置（NEO4J_URI、NEO4J_USERNAME、NEO4J_PASSWORD），与 Claude Desktop 的 MCP 配置格式完全兼容。

---

局限与注意事项

mcp-neo4j-cypher 依赖 APOC 插件进行 schema 探测，如果你使用的是 Neo4j 社区版或 Aura Free 层，需要确认 APOC 插件是否可用。生成 Cypher 查询的质量取决于 AI 模型的能力，复杂查询可能需要多次交互才能得到正确结果。

此外，作为 Labs 项目，该仓库不提供 SLA 保证，版本更新可能带来非向后兼容的变更，生产环境使用前请锁定版本。

最后，该项目仅处理 Neo4j 数据库层面，不涉及前端 UI，需要通过 MCP 客户端（Claude、Cursor 等）来使用。

---

行业意义：图数据库与大模型的深度融合

mcp-neo4j 代表着 LLM 与图数据库融合的一个成熟路径：通过 MCP 协议，AI 模型获得了对图结构数据的原生理解能力，无需手写复杂查询即可完成知识推理与数据探索。这种「AI + 图数据库」的范式正在快速普及，Neo4j 作为图数据库领域的领导者，其 MCP 实现对整个生态具有示范效应。

从项目活跃度来看（345 commits，56 个版本标签，持续更新），图数据库 + MCP 这个方向正处于快速增长期，预计未来会有更多云服务商和企业将类似集成纳入标准开发工具链。