Neo4j MCP Canary — 金丝雀先行，好让我们其余人知道接下来会发生什么

Neo4j MCP Canary 是 Neo4j MCP 服务器的一个快速迭代的实验性版本，面向希望在官方服务器考虑纳入新功能之前探索这些新兴能力的客户。

它基于 Neo4j 官方 Model Context Protocol (MCP) 服务器的源代码构建，旨在通过实验探索潜在的新能力。

由于这是一个 labs 项目，请注意：

• 它不受支持。

• 它可能在其自身版本之间以及与官方 Neo4j MCP 服务器之间存在破坏性变更。

• 使用前应进行测试。

欢迎贡献——我们始终乐于接受新想法，尤其是在这个 canary 渠道中。

不要假设 canary 一定适用于你的场景。请先测试。

前提条件

• 一个正在运行的 Neo4j 数据库实例；可选方案包括 Aura、Neo4j Desktop 或 自托管。

• 在 Neo4j 实例中安装 APOC 插件（必需——get-schema 使用 apoc.meta.schema）。

• 任何兼容 MCP 的客户端（例如 VSCode 及其 MCP 支持）。

⚠️ 已知问题：Neo4j 5.26.18 的 APOC 存在一个缺陷，会导致 get-schema 工具失败。该问题已在 5.26.19 及以上版本中修复。如果你正在使用 5.26.18，请升级。详见 #136。

Related MCP server: FastMCP Production-Ready Server

启动检查与自适应运行

服务器在启动时会执行若干预检检查，以确保你的环境配置正确。

STDIO 模式——强制要求

在 STDIO 模式下，服务器会验证以下内容。如果任何检查失败（例如配置无效、凭据错误、缺少 APOC），服务器将不会启动：

• 与你的 Neo4j 实例的有效连接。

• 执行查询的能力。

• APOC 插件是否存在。

HTTP 模式——跳过验证

在 HTTP 模式下，启动验证检查会被跳过，因为凭据来自每个请求的认证头。服务器会立即启动，而无需连接 Neo4j。唯一的例外是 Query API 模式：其最低版本检查在两种传输模式下都会在启动时运行，因为它只需要一个未认证的 GET 请求，并且不依赖于每个请求的凭据。

可选要求

如果缺少可选依赖，服务器会以自适应模式启动。例如，如果未检测到 Graph Data Science (GDS) 库，服务器仍会启动，但会自动禁用依赖 GDS 的工具，例如 list-gds-procedures。所有其他工具仍然可用。

安装（二进制）

发布版本：https://github.com/neo4j-labs/neo4j-mcp-canary/releases

1. 下载适用于你的操作系统/架构的压缩包。

2. 解压并将 neo4j-mcp-canary 放到你的 PATH 中。

Mac / Linux：

在 Mac 上，首次尝试运行该二进制文件时可能会收到警告。如果出现这种情况，请通过系统设置 → 隐私与安全性批准。

chmod +x neo4j-mcp-canary
sudo mv neo4j-mcp-canary /usr/local/bin/

Windows（PowerShell / cmd）：

move neo4j-mcp-canary.exe C:\Windows\System32

验证安装：

neo4j-mcp-canary -v

应输出已安装的版本。

从源码构建

需要 Go 1.25.3+（参见 go.mod）。

使用 Task 为当前平台构建：

task build

这将生成 bin/neo4j-mcp-canary。如果没有 Task，等效命令为：

go build -C cmd/neo4j-mcp -o ../../bin/

为 macOS / Linux 交叉编译

通过设置 GOOS/GOARCH 并禁用 cgo 进行交叉编译（该代码库是纯 Go，因此 CGO_ENABLED=0 会生成完全静态的二进制文件，在目标机器上没有任何运行时依赖）：

CGO_ENABLED=0 GOOS=darwin  GOARCH=amd64 go build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary_darwin_amd64
CGO_ENABLED=0 GOOS=darwin  GOARCH=arm64 go build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary_darwin_arm64
CGO_ENABLED=0 GOOS=linux   GOARCH=amd64 go build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary_linux_amd64
CGO_ENABLED=0 GOOS=linux   GOARCH=arm64 go build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary_linux_arm64

要将版本写入二进制文件（-v / --version），请传入 ldflags 覆盖项——发布流水线对带标签的构建就是这么做的：

go build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary \
  -ldflags "-X 'main.Version=$(git rev-parse --short HEAD)'"

如果没有它，Version 默认为 "development"，这也会禁用遥测，无论 NEO4J_TELEMETRY 如何设置（参见 遥测）。

官方多平台发布压缩包（包括 Windows）由 GoReleaser 根据 .goreleaser.yaml 构建——参见 安装（二进制） 下载这些压缩包，而无需在本地构建。

传输模式

Neo4j MCP Canary 服务器支持两种传输模式：

• STDIO（默认）：通过 stdin/stdout 进行标准 MCP 通信，适用于桌面客户端（Claude Desktop、VSCode）。

• HTTP：基于 RESTful HTTP 的服务器，使用每个请求的 Bearer token 或基本认证，适用于基于 Web 的客户端和多租户场景。在无法使用标准 Authorization 头的情况下，可以配置自定义头名称。

主要区别

有关两种模式的配置说明，请参阅客户端设置指南。

未经认证的 MCP 客户端请求

默认情况下，使用 HTTP(S) 传输时，MCP 客户端可以在未经认证的情况下发送四个请求。某些集成（AWS AgentCore、AWS Gateway 等）依赖此机制作为初始健康检查：

• ping

• initialize

• tools/list

• notifications/initialize

如果你不需要这些，可以通过下面的变量单独强制认证。

TLS/HTTPS 配置

使用 HTTP 传输时，可通过下面的变量启用 TLS 以实现安全通信。

安全配置

• 最低 TLS 版本： TLS 1.2（可用时协商 TLS 1.3）

• 密码套件： Go 的安全默认密码套件

• 默认端口： 启用 TLS 时自动使用 443

示例

export NEO4J_URI="bolt://localhost:7687"
export NEO4J_TRANSPORT_MODE="http"
export NEO4J_MCP_HTTP_TLS_ENABLED="true"
export NEO4J_MCP_HTTP_TLS_CERT_FILE="/path/to/cert.pem"
export NEO4J_MCP_HTTP_TLS_KEY_FILE="/path/to/key.pem"

neo4j-mcp-canary
# Server listens on https://127.0.0.1:443 by default

生产环境使用： 对于生产部署，请使用来自受信任 CA（Let's Encrypt、你所在组织的 CA 等）的证书。

有关证书生成、TLS 测试和生产部署的详细说明，请参阅 CONTRIBUTING.md。

配置选项

neo4j-mcp-canary 服务器通过环境变量、CLI 标志和/或可选的配置文件进行配置。CLI 标志优先于环境变量，环境变量优先于可选的配置文件。

环境变量

核心连接与行为：

通过 Query API 而非 Bolt 连接

NEO4J_URI 的 scheme 决定服务器与 Neo4j 通信时使用哪种线路协议——无需单独的标志：

• bolt://、bolt+s://、neo4j://、neo4j+s:// 等 → Bolt 驱动（默认，行为不变）。

• http:// 或 https:// → Neo4j Query API，即 Neo4j 基于 HTTP 的查询接口。适用于仅暴露 HTTP 或出于其他原因不希望使用 Bolt 的部署。

Query API 模式要求 Neo4j 2026.07 或更高版本（日历版本发布），或 5.27-aura 或更高版本（仅限经典版本 Aura 发布——不带 -aura 后缀的纯经典版本不受支持）。此下限比 Query API 自身的正式发布（2026.06）晚一个版本：read-cypher 对写查询的拒绝依赖于查询响应中的 queryType 字段，而 Neo4j 直到 2026.07 才引入该字段——2026.06 服务器在运行前没有可靠的信号来将查询分类为只读。服务器在启动时会检查所连接实例报告的版本是否达到此下限（通过对基础 URI 发起未认证的 GET 请求），如果版本过旧则拒绝启动，错误信息会指明检测到的版本和最低要求。

NEO4J_USERNAME/NEO4J_PASSWORD 以及按请求提供的 Basic/Bearer 凭据在 Query API 模式下的工作方式与 Bolt 相同——参见传输模式和身份验证方法（HTTP 模式）。

Cypher 执行保护措施（参见 Cypher 执行保护措施）：

HTTP 传输、TLS 和身份验证（参见上表）。

CLI 标志

你可以使用 CLI 标志覆盖任何环境变量：

neo4j-mcp-canary \
  --neo4j-uri "bolt://localhost:7687" \
  --neo4j-username "neo4j" \
  --neo4j-password "password" \
  --neo4j-database "neo4j" \
  --neo4j-read-only false \
  --neo4j-telemetry true

可用标志：

连接与行为

• --neo4j-uri — 覆盖 NEO4J_URI

• --neo4j-username — 覆盖 NEO4J_USERNAME

• --neo4j-password — 覆盖 NEO4J_PASSWORD

• --neo4j-database — 覆盖 NEO4J_DATABASE

• --neo4j-read-only — 覆盖 NEO4J_READ_ONLY（true / false）

• --neo4j-telemetry — 覆盖 NEO4J_TELEMETRY（true / false）

• --neo4j-schema-sample-size — 覆盖 NEO4J_SCHEMA_SAMPLE_SIZE

• --neo4j-output-format — 覆盖 NEO4J_OUTPUT_FORMAT（json / toon）

Cypher 执行保护措施

• --neo4j-cypher-max-rows — 覆盖 NEO4J_CYPHER_MAX_ROWS（0 表示禁用）

• --neo4j-cypher-max-bytes — 覆盖 NEO4J_CYPHER_MAX_BYTES（0 表示禁用）

• --neo4j-cypher-timeout — 覆盖 NEO4J_CYPHER_TIMEOUT（秒；0 表示禁用）

• --neo4j-cypher-max-estimated-rows — 覆盖 NEO4J_CYPHER_MAX_ESTIMATED_ROWS（0 表示禁用）

传输 / HTTP

• --neo4j-transport-mode — stdio 或 http

• --neo4j-http-host — 覆盖 NEO4J_MCP_HTTP_HOST

• --neo4j-http-port — 覆盖 NEO4J_MCP_HTTP_PORT

• --neo4j-http-allowed-origins — 覆盖 NEO4J_MCP_HTTP_ALLOWED_ORIGINS（逗号分隔的 CORS 来源）

• --neo4j-http-tls-enabled — 覆盖 NEO4J_MCP_HTTP_TLS_ENABLED

• --neo4j-http-tls-cert-file — 覆盖 NEO4J_MCP_HTTP_TLS_CERT_FILE

• --neo4j-http-tls-key-file — 覆盖 NEO4J_MCP_HTTP_TLS_KEY_FILE

• --neo4j-http-auth-header-name — 覆盖 NEO4J_HTTP_AUTH_HEADER_NAME

• --neo4j-http-allow-unauthenticated-ping — 覆盖 NEO4J_HTTP_ALLOW_UNAUTHENTICATED_PING

• --neo4j-http-allow-unauthenticated-tools-list — 覆盖 NEO4J_HTTP_ALLOW_UNAUTHENTICATED_TOOLS_LIST

• --neo4j-http-allow-unauthenticated-initialize — 覆盖 NEO4J_HTTP_ALLOW_UNAUTHENTICATED_INITIALIZE

• --neo4j-http-allow-unauthenticated-notifications-initialize — 覆盖 NEO4J_HTTP_ALLOW_UNAUTHENTICATED_NOTIFICATIONS_INITIALIZE

运行 neo4j-mcp-canary --help 可查看带描述的完整列表。

配置文件

作为环境变量的最低优先级替代方案，neo4j-mcp-canary 可以从可选的 JSON 或 YAML 文件中读取配置：

neo4j-mcp-canary --config-file /etc/neo4j-mcp/config.yaml
# or
NEO4J_CONFIG_FILE=/etc/neo4j-mcp/config.yaml neo4j-mcp-canary

键是对应环境变量的小写形式：

neo4j_uri: bolt://localhost:7687
neo4j_username: neo4j
neo4j_password: password
neo4j_read_only: false
neo4j_transport_mode: http
neo4j_http_tls_enabled: true
neo4j_cypher_max_rows: 500

也接受等效的 JSON（.json 扩展名）。仅支持标量值（字符串、数字、布尔值）——嵌套对象或列表会导致启动错误。CLI 标志或环境变量的值始终优先于配置文件；--config-file 读取或解析失败会导致启动错误。

为服务器添加新的配置参数（环境变量 + CLI 标志 + 配置文件键，三者同时添加）意味着在 internal/config/schema.go 的 fields 切片中添加一个条目——有关格式，请参阅该文件中的文档注释。

响应格式（JSON 与 TOON）

工具响应（read-cypher、write-cypher、get-schema、list-gds-procedures）默认以 JSON 呈现。将 NEO4J_OUTPUT_FORMAT（或 --neo4j-output-format）设置为 toon，即可将它们呈现为 TOON（令牌导向对象表示法）——这是一种紧凑且仍然人类可读的格式，与 JSON 相比可减少 LLM 的令牌消耗，尤其适用于这些工具返回的表格行形状：

neo4j-mcp-canary --neo4j-output-format toon
# or
NEO4J_OUTPUT_FORMAT=toon neo4j-mcp-canary

read-cypher 结果以 JSON 呈现：

{
  "rows": [
    { "name": "Alice", "age": 30 },
    { "name": "Bob", "age": 25 }
  ],
  "rowCount": 2,
  "truncated": false
}

相同结果以 TOON 呈现：

rowCount: 2
rows[2]{age,name}:
  30,Alice
  25,Bob
truncated: false

无效值会回退到 json，并在 stderr 上输出警告，方式与 NEO4J_LOG_FORMAT 相同。

Cypher 执行保护措施

read-cypher 和 write-cypher 受到四层保护措施的保护，这些措施共同防止过于激进的 LLM 挂起 MCP 传输或耗尽数据库。每一层捕获不同的故障模式；它们共同构成纵深防御。

将任何值设置为 0 即可禁用该特定层。

截断信封

当行数上限或字节数上限触发时，工具会返回已收集的行以及一个截断信封：

{
  "rows": [ /* ... */ ],
  "rowCount": 1000,
  "truncated": true,
  "truncationReason": "rows",
  "maxRows": 1000,
  "hint": "Results were truncated at 1000 rows. Add a LIMIT clause or a more selective filter and retry for a complete result."
}

调用方（包括 LLM 代理）可以编程方式读取 truncated / truncationReason / hint，并使用更严格的查询重试，而不是看到不透明的传输级故障。

超时与取消错误

当 NEO4J_CYPHER_TIMEOUT 触发时，工具会返回一个分类错误，指明配置的限制，并提供针对工具的具体修复建议（对于 read-cypher：绑定可变长度模式、添加 WHERE 过滤器或使用 LIMIT；对于 write-cypher：减小批处理大小、缩小 MATCH 范围或使用 apoc.periodic.iterate）。调用方取消（与超时不同）会以简洁的 cancelled 消息呈现，不附带修复建议。

规划器估算拒绝

规划器估算保护会在查询运行前读取 EXPLAIN 计划的根节点 EstimatedRows。由于 Neo4j 会将 LIMIT 折叠到根节点估算中，合法的 MATCH ... LIMIT 100 查询会以约 100 的估算值顺利通过，而对数百万行标签的裸 MATCH 会在开始前被拒绝。

身份验证方法（HTTP 模式）

使用 HTTP 传输模式时，Neo4j MCP Canary 服务器支持两种身份验证方法，以适应不同的部署场景。

Bearer Token 身份验证

Bearer Token 身份验证支持与使用 SSO/OAuth/OIDC 进行身份管理的 Neo4j Enterprise Edition 和 Neo4j Aura 环境无缝集成。此方法适用于：

• 使用集中式身份提供程序（Okta、Azure AD 等）的企业部署

• 配置了 SSO 的 Neo4j Aura 数据库

• 需要符合 OAuth 2.0 的组织

• 多因素身份验证场景

示例：

curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Bearer Token 从你的身份提供程序获取，并传递给 Neo4j 进行身份验证。MCP 服务器充当透传，将令牌转发给 Neo4j 的身份验证系统。

基本身份验证

传统的用户名/密码身份验证，适用于：

• Neo4j Community Edition

• 开发与测试环境

• 不使用 SSO 的直接数据库凭据

示例：

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

客户端配置

要配置 MCP 客户端（VSCode、Claude Desktop 等）使用 Neo4j MCP Canary 服务器，请参阅：

📘 客户端设置指南 – STDIO 和 HTTP 模式的完整配置。

工具与用法

提供的工具：

只读模式标志

通过设置 NEO4J_READ_ONLY=true 启用只读模式（接受：true / false；默认：false）。

你也可以使用 CLI 标志：

neo4j-mcp-canary \
  --neo4j-uri "bolt://localhost:7687" \
  --neo4j-username "neo4j" \
  --neo4j-password "password" \
  --neo4j-read-only true

启用后，写工具（例如 write-cypher）不会暴露给客户端。

查询分类

read-cypher 会在调用者的查询前加上 EXPLAIN，以便在执行前将其分类为读或写。后果：

• 写操作（CREATE、MERGE、DELETE、SET、REMOVE 等）——被拒绝，并返回一条消息，引导调用方使用 write-cypher。

• Schema/DDL 操作（CREATE INDEX、DROP CONSTRAINT 等）——被拒绝，返回相同消息。

• 管理命令（SHOW USERS、SHOW DATABASES 等）——被拒绝，返回相同消息。

• EXPLAIN 前缀——被拒绝，并返回一条专门的消息，说明失控查询保护已由规划器估算守卫和执行超时提供，并提示如需分析计划请使用 write-cypher。

• PROFILE 前缀——被拒绝，并返回一条消息，引导调用方使用 write-cypher。

• 只读 SHOW 命令（SHOW INDEXES、SHOW CONSTRAINTS、SHOW PROCEDURES、SHOW FUNCTIONS）——允许。

如果被包装的查询产生语法错误，服务器会在返回前从错误文本、列偏移量和脱字符对齐中剥离内部的 EXPLAIN 前缀——这样错误信息读起来就像调用方直接提交了原始查询一样。

read-cypher / write-cypher 的响应格式

驱动程序类型被包装为符合 Cypher 约定的 camelCase JSON 结构：

• 节点： { "elementId": "...", "labels": [...], "properties": {...} }

• 关系： { "elementId": "...", "startElementId": "...", "endElementId": "...", "type": "...", "properties": {...} }

• 路径： { "nodes": [...], "relationships": [...] }

• 点： { "x": ..., "y": ..., "srid": ... }（3D 时还有 z）

• Date / Time / DateTime / LocalTime / LocalDateTime / Duration： ISO 8601 字符串

已弃用的数字型 id / startId / endId 标识符不会暴露——elementId / startElementId / endElementId 是唯一返回的标识符。

反馈

give-feedback 允许代理以单个 feedback 字符串参数提交关于 MCP 服务器本身的自由文本反馈——正面或负面均可——上限为 300 个字符（在公开的工具 schema 和处理程序中都有强制校验，以防客户端在发送前未验证 schema）。它用于反馈服务器的工具、行为或文档，而不是用于报告 Cypher/数据库错误。

反馈会作为 Mixpanel 事件与服务器的其他遥测数据一起发送，因此只有在启用遥测时才会被记录（参见遥测）——无论是否启用，工具调用本身始终成功。

使用指南

来自金丝雀测试的经验教训，可帮助 LLM（或人类）充分利用 read-cypher：

1. 在数据库中进行聚合。 count、sum、avg、collect、reduce、percentileCont、stDev 等聚合操作会折叠为一行，不受行数上限影响。像 UNWIND range(1, 50000) AS i RETURN sum(i) 这样的查询可以顺利运行；而同样的范围逐行流式返回时会在行数上限处被截断。

2. 始终为探索性查询使用 LIMIT。 行数上限会截断裸 MATCH 返回；截断信封的 hint 字段会提示调用方添加 LIMIT。优先使用你自己选择的 LIMIT，而不是服务器强加的。

3. 对宽节点收窄 RETURN 投影。 当一条记录携带大量属性（例如包含 19 个字段的完整 Company 节点）时，字节上限会先于行数上限触发。只返回你需要的字段（RETURN c.name, c.companyNumber），而不是整个节点。

4. 使用参数，包括嵌套映射。 参数占位符（$name）从 params 对象绑定；嵌套访问有效（$config.thresholds.pr）。缺少必需参数会产生明确的 ParameterMissing 错误；多余参数会被静默忽略。

5. 在比较中明确类型。 跨类型比较（如 t.amount > "foo"）会求值为 null 并静默过滤掉所有内容——不会报错，只会得到空结果集。当结果形状出乎意料时，请在调用方验证传入的参数类型。

6. SHOW INDEXES / SHOW CONSTRAINTS 是允许的。 在编写依赖索引的查询之前，或调试匹配缓慢的原因时很有用。

7. read-cypher 不暴露 EXPLAIN 和 PROFILE。 失控查询保护已由规划器估算守卫和执行超时处理。如果你需要带运行时统计信息的分析计划，请使用带 PROFILE 的 write-cypher。

8. 返回路径时注意重复的负载。 RETURN p, nodes(p), relationships(p) 会使序列化负载增加三倍。请返回路径或其组成部分，不要两者都返回。

9. 长时间运行的查询会返回分类错误。 当 NEO4J_CYPHER_TIMEOUT 触发时，错误会指明超时值并建议修复方法（限制可变长度模式、添加 WHERE 过滤器、使用 LIMIT），而不是返回驱动程序的原始 context deadline exceeded。

10. 对缺失数据使用 OPTIONAL MATCH。 当按 ID 查找且某些 ID 可能不存在时，OPTIONAL MATCH 会对未命中的情况返回 null，而不是丢弃行——更适合批量查找。

11. 默认值是经过校准的，而非随意设定。 1000 行 / ~900 KB / 30s / 1M 规划器估算覆盖了绝大多数探索性和生产查询。对于批量导出工作负载可增大这些值；对于高流量代理部署可减小这些值。

自然语言提示示例

可在 Copilot 或任何其他 MCP 客户端中尝试的提示：

• "我的 Neo4j 实例包含什么？列出所有节点标签、关系类型和属性键。"

• "查找所有 Person 节点并显示它们最重要的关系，限制为 50 条结果。"

• "我的数据库上存在哪些索引和约束？"

• "汇总交易图：总计数、平均金额，以及按 PageRank 排名前 5 的客户。"

安全提示

• 使用受限的 Neo4j 用户进行探索。

• 在生产数据库中执行 LLM 生成的 Cypher 之前先进行审查。

• 对于任何不应修改图的部署，保持 NEO4J_READ_ONLY=true。

• 除非你有特定理由更改，否则将 Cypher 安全防护保持默认设置。

日志

服务器使用结构化日志，支持多种日志级别和输出格式。

配置

日志级别（NEO4J_LOG_LEVEL，默认值：info）

控制详细程度。支持所有 MCP 日志级别：debug、info、notice、warning、error、critical、alert、emergency。

日志格式（NEO4J_LOG_FORMAT，默认值：text）

• text — 人类可读（默认）

• json — 结构化 JSON（适用于日志聚合）

遥测

默认情况下，neo4j-mcp-canary 会收集匿名使用数据以帮助改进产品。这包括所使用的工具、操作系统和 CPU 架构等信息。不会收集任何个人或敏感信息。

要禁用遥测，请设置 NEO4J_TELEMETRY=false（接受的值：true / false；默认值：true）。你也可以使用 --neo4j-telemetry CLI 标志。

文档

📘 客户端设置指南 – 配置 VSCode、Claude Desktop 和其他 MCP 客户端（STDIO 和 HTTP 模式） 📚 贡献指南 – 贡献工作流、开发环境、模拟与测试

问题 / 反馈：请打开一个 GitHub issue 并附上复现细节（请省略敏感数据）。