首页 / 文章

使用 Docker 和 VS Code 在自己的机器上运行 Neo4j MCP 服务器

使用 Docker Compose 自主部署 Neo4j 及其官方 MCP 服务器,通过 HTTP 的基本认证机制进行安全保护,以 Agent 模式连接 VS Code,然后查询示例图数据。

发布者:REACTAPP.TOP阅读约 8 分钟1743 词

来源: Run the Neo4j MCP Server Locally with Docker (No Codespaces Needed)

Neo4j的官方MCP服务器是个小型程序,借助Docker,整个架构可在笔记本电脑上大约半小时内运行起来。这对于正在学习GraphAcademy中关于使用Neo4j MCP工具进行开发的课程的人来说非常重要,因为该课程以GitHub Codespaces为前提,而Codespaces每月有免费使用额度,最终会用完。自行托管则无需受此限制,且完全免费。以下步骤已完整执行,同时展示了MCP各组件之间的协同方式。

最终能构建出什么

VS Code (host)  ──HTTP /mcp + auth──►  neo4j-mcp (server)  ──Bolt──►  Neo4j (database)

该架构由三个独立的部分组成,清晰地了解这些组成部分就能掌握其运作原理。

  • 主机:即MCP客户端,例如VS Code、Claude Desktop或Cursor。它负责处理MCP协议,完全不知道Neo4j的存在。
  • MCP服务器:即neo4j-mcp桥接程序,它将read-cypher之类的MCP工具调用转换为实际的Bolt查询语句。
  • 数据库:即Neo4j本身。

一个常见的误解是认为某个远程的“MCP数据库”存在于云端,其实并非如此。MCP服务器是一个在本地运行的程序,它会连接到指定的数据库。

前置条件

必须已安装并运行 Docker Desktop,可通过 docker --version 进行确认。还需要支持 MCP 的 VS Code 以及一个终端。无需单独安装 Python 和 Neo4j,因为 Docker 已涵盖这两者。

步骤 1:编写 Docker 配置文件

创建一个项目文件夹,并在其中放入 docker-compose.yml 文件。该文件定义了两个服务,首先是数据库:

services:
  neo4j:
    image: neo4j:5.26
    container_name: neo4j
    ports:
      - "7474:7474"          # Neo4j Browser  -> http://localhost:7474
      - "7687:7687"          # Bolt
    environment:
      NEO4J_AUTH: "neo4j/password123"
      NEO4J_PLUGINS: '["apoc","graph-data-science"]'   # needed for get-schema + GDS tool
    volumes:
      - neo4j_data:/data
    healthcheck:
      test: ["CMD-SHELL", "cypher-shell -u neo4j -p password123 'RETURN 1' || exit 1"]
      interval: 10s
      timeout: 10s
      retries: 12
      start_period: 30s

其次是MCP服务器,它是直接从官方仓库的指定标签处构建的:

  neo4j-mcp:
    build:
      context: "https://github.com/neo4j/mcp.git#v1.5.2"   # builds the official server from source
    container_name: neo4j-mcp
    depends_on:
      neo4j:
        condition: service_healthy
    ports:
      - "8000:8000"          # MCP endpoint -> http://localhost:8000/mcp
    environment:
      NEO4J_URI: "bolt://neo4j:7687"
      NEO4J_DATABASE: "neo4j"
      NEO4J_TRANSPORT_MODE: "http"     # networked service, not a stdio subprocess
      NEO4J_MCP_HTTP_HOST: "0.0.0.0"   # bind all interfaces so the host can reach it
      NEO4J_MCP_HTTP_PORT: "8000"      # must be >1024 (container runs as non-root)volumes:
  neo4j_data:

这里有两个细节值得注意。

  • 使用 HTTP 传输而非 stdio。 该课程以 stdio 模式启动服务器,即主机将其作为子进程运行。而此实现方式则将其作为独立的 HTTP 服务运行,更接近实际部署环境,且允许任何客户端通过 URL 进行连接。
  • 为何选择这些数值。 容器并非以 root 身份运行,因此无法绑定 1024 以下的特权端口。正因如此,才使用 8000 作为 80 的替代端口。在 HTTP 模式下,服务器按设计也会拒绝 NEO4J_USERNAME 和 NEO4J_PASSWORD 这些环境变量。凭据会通过 HTTP Basic Auth 在每次请求中传递,这与生产环境中的认证方式一致,因此无需使用这些变量。

步骤 2:启动服务器

docker compose up -d --build

首次运行时会下载 Neo4j 镜像,编译 Go MCP 服务器,并下载 APOC 和 GDS 插件。大约一分钟后,检查两个容器是否均已启动:

docker compose ps

等待 neo4j 返回 (healthy) 状态。

步骤 3:验证服务器

MCP 接口地址为 http://localhost:8000/mcp。在浏览器中打开该地址会显示 Method Not Allowed: only POST is supported 的提示。这实际上是个好现象,因为它说明服务器正在运行,只是浏览器发送了 GET 请求。

建议使用 curl 进行正式测试。首先确认系统是否启用了身份验证:

curl -i -X POST http://localhost:8000/mcp        # expect 401 Unauthorized

接下来,使用数据库凭据进行身份验证的同时列出相关工具:

curl -s -u neo4j:password123 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
  http://localhost:8000/mcp

响应中应包含 get-schema、read-cypher 和 write-cypher 这三个名称。

为何只显示三个工具

课程中介绍了四种工具,缺失的是 list-gds-procedures。这并非故障,因为该工具会在 MCP 的 initialize 握手过程中延迟注册,且仅在安装了 Graph Data Science 后才会注册。如果直接发送 tools/list 请求,就会跳过该握手过程,因此第四种工具不会显示。请先发送 initialize 请求,然后再列出工具列表:

curl -s -u neo4j:password123 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}},"id":1}' \
  http://localhost:8000/mcp
curl -s -u neo4j:password123 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":2}' \
  http://localhost:8000/mcp

现在四个工具都显示出来了。像 VS Code 这样的实际客户端会自行运行 initialize,因此这一特性仅会影响原始的 curl 调用。

第 4 步:连接 VS Code

在项目中创建 .vscode/mcp.json 文件:

{
    "servers": {
        "neo4j": {
            "type": "http",
            "url": "http://localhost:8000/mcp",
            "headers": {
                "Authorization": "Basic bmVvNGo6cGFzc3dvcmQxMjM="
            }
        }
    }
}

Authorization值其实就是neo4j:password123的base64编码。修改密码后,需使用以下方法重新生成该值:

printf 'neo4j:yourpassword' | base64

最常见的错误是针对这种 Docker 环境重复使用课程中的 stdio 配置("type": "stdio", "command": "neo4j-mcp")。这会告诉 VS Code 启动一个并不存在的本地二进制文件。容器化服务器需要上述的 http 配置。

在 VS Code 中,通过 Cmd/Ctrl + Shift + P 打开命令面板,运行 MCP: List Servers,选择 neo4j,然后点击 Start Server。接着将 Chat 模式切换为 Agent 模式(Cmd/Ctrl + Shift + I),请求列出带有编号和描述的所有可用 MCP 工具,最终会返回四种工具。

第 5 步:实际应用

本地数据库初始为空,因此另一个可临时使用的MCP容器可以指向Neo4j的公共电影演示数据库,即课程中使用的那个数据库,只不过端口不同。主应用栈保持不变:

docker run --rm -d --name mcp-movies \
  -e NEO4J_URI="neo4j+s://demo.neo4jlabs.com" \
  -e NEO4J_DATABASE="recommendations" \
  -e NEO4J_TRANSPORT_MODE="http" \
  -e NEO4J_MCP_HTTP_HOST="0.0.0.0" \
  -e NEO4J_MCP_HTTP_PORT="8001" \
  -p 8001:8001 \
  <your-project-name>-neo4j-mcp

图像名称由 docker compose 生成。运行 docker images 即可查看,名称大概为 yourfolder-neo4j-mcp。

若要读取模式并查看 User 具有的关联关系,可调用 read-cypher:

curl -s -u recommendations:recommendations -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"read-cypher","arguments":{"query":"MATCH (u:User)-[r]->() RETURN DISTINCT type(r) AS rel"}},"id":2}' \
  http://localhost:8001/mcp

答案是 RATED,即 (:User)-[:RATED]->(:Movie)。

若要查询评分最高的电影,需加入非空校验,因为并非所有电影都有评分:

curl -s -u recommendations:recommendations -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"read-cypher","arguments":{"query":"MATCH (m:Movie) WHERE m.imdbRating IS NOT NULL RETURN m.title AS title, m.imdbRating AS rating ORDER BY m.imdbRating DESC LIMIT 1"}},"id":3}' \
  http://localhost:8001/mcp

演示结束后,停止该容器:

docker stop mcp-movies

第6步:添加一个简易应用

课程最后会让学习者编写一个Python命令行工具,用于返回某一类型中的前五部电影。这个精简版本通过查询参数传递类型信息,而非字符串拼接,并且会过滤掉评分为空的条目:

import os, sys
from neo4j import GraphDatabase
QUERY = """
MATCH (m:Movie)-[:IN_GENRE]->(:Genre {name: $genre})
WHERE m.imdbRating IS NOT NULL
RETURN m.title AS title, m.imdbRating AS rating
ORDER BY m.imdbRating DESC
LIMIT 5
"""def main():
    uri = os.environ["NEO4J_URI"]
    user = os.environ["NEO4J_USERNAME"]
    pwd = os.environ["NEO4J_PASSWORD"]
    db = os.environ.get("NEO4J_DATABASE", "neo4j")    genre = input("Enter a movie genre: ").strip()
    with GraphDatabase.driver(uri, auth=(user, pwd)) as driver:
        driver.verify_connectivity()
        records, _, _ = driver.execute_query(QUERY, genre=genre, database_=db)    print(f"\nTop {len(records)} '{genre}' movies:")
    for i, r in enumerate(records, 1):
        print(f"  {i}. {r['title']} ({r['rating']})")if __name__ == "__main__":
    main()

在演示数据库上运行它:

pip install neo4j
export NEO4J_URI="neo4j+s://demo.neo4jlabs.com"
export NEO4J_USERNAME="recommendations"
export NEO4J_PASSWORD="recommendations"
export NEO4J_DATABASE="recommendations"
python3 movie_recommender.py      # then type: Mystery

已取得的成果

大约半小时内,完整的Neo4j MCP栈即可在本地运行,无需使用Codespaces,也不会产生云服务费用:

  • 包含APOC和GDS功能的Neo4j,以及官方的neo4j-mcp服务器,均基于Docker部署
  • 作为经过身份验证的HTTP服务的MCP服务器
  • 以Agent模式连接的VS Code
  • 通过MCP工具以及上层的小型Python应用执行实际查询

为何自行托管能带来更多收获

这很容易被理解为一种规避配额限制的方法,但亲自运行服务器其实能展现出更有价值的东西。MCP正逐渐成为AI智能体接入真实系统——如数据库、API和内部工具——的标准途径。而有趣的工程问题恰恰出现在这种架构的各个环节:服务器如何传输?请求如何进行身份验证?又该如何防止智能体执行具有破坏性的查询?

通过 HTTP 运行服务器,并采用每次请求的身份验证机制及只读开关,这些问题就会显现出来,而预构建的托管沙箱则会将它们隐藏起来。由于越来越多的代理用于处理实时生产数据,将 MCP 服务器作为可控且可观测的服务来运行,比依赖他人托管的黑盒更为重要。在通过 TLS 及密钥管理器部署在网关后的实际环境中,也需遵循相同的架构。

故障排除

  • 浏览器中显示 Method Not Allowed: 请求为 GET 方式,而端点仅接受 POST 请求。请使用 curl 或 MCP 客户端。
  • 401 Unauthorized: 基本身份验证缺失或错误。请使用数据库的用户名和密码。
  • 仅列出三个工具: 先发送 initialize 命令,并确保已安装 APOC 和 GDS。
  • get-schema 失败:未安装 APOC。请将其添加到 NEO4J_PLUGINS 中。
  • 服务器拒绝启动并提示身份验证问题:在 HTTP 模式下设置了 NEO4J_USERNAME 或 NEO4J_PASSWORD。请将这两项都移除。
  • VS Code 显示服务器“需要交互才能启动”: mcp.json 中仍保留着标准输入输出配置。请改为使用 http 模式下的配置。
  • 绑定端口时被拒绝权限:由于容器并非 root 用户,需将 NEO4J_MCP_HTTP_PORT 设置为大于 1024 的值。
  • 进一步阅读

    Neo4j MCP 服务器文档及官方 MCP 规范中包含了详细说明。

    相关阅读

  • 使用令牌和 Docker 将私有 GitHub 仓库连接到 Claude Desktop — 创建具有安全权限范围的经典 GitHub 令牌,通过 Docker 将 GitHub MCP 服务器添加到 Claude Desktop,进行测试,进而用于代码审查、问题分类及变更日志管理。