使用 Docker 和 VS Code 在自己的机器上运行 Neo4j MCP 服务器
使用 Docker Compose 自主部署 Neo4j 及其官方 MCP 服务器,通过 HTTP 的基本认证机制进行安全保护,以 Agent 模式连接 VS Code,然后查询示例图数据。
来源: 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 中。NEO4J_USERNAME 或 NEO4J_PASSWORD。请将这两项都移除。mcp.json 中仍保留着标准输入输出配置。请改为使用 http 模式下的配置。NEO4J_MCP_HTTP_PORT 设置为大于 1024 的值。进一步阅读
Neo4j MCP 服务器文档及官方 MCP 规范中包含了详细说明。
相关阅读
- 使用 OAuth 2.0 和工具级权限范围保护 Spring AI MCP 服务器 — 构建 OAuth 授权服务器,将 Spring AI MCP 服务器转换为资源服务器,在 MCP Inspector 中进行测试,然后通过权限范围限制单个工具的访问。
- 实用笔记:微软构建了 Playwright MCP 服务器,然后要求大家这样做 — 对“实用笔记:微软构建了 Playwright MCP 服务器,然后要求大家这样做”中的内容进行详细操作指引:包括合同规范、检查项以及供采用该模式的团队使用的现成代码片段。