Neo4j MCP Canary

Neo4j MCP金丝雀-- _金丝雀先走，所以我们其他人都知道会发生什么_

Neo4j MCP Canary是Neo4j MCP服务器的一个快速发展的实验版本，面向那些希望在考虑将其作为官方服务器之前探索新兴功能的客户。

该变体基于Neo4j的官方模型上下文协议（MCP）服务器的源代码构建，旨在通过实验探索潜在的新功能。

由于这是一个实验室项目，请注意：

• 它不受支持。
• 它可能包含其自身版本之间以及与官方Neo4j MCP服务器之间的突破性更改。
• 使用前应进行测试。

欢迎您做出贡献——我们始终对新想法持开放态度，尤其是在这个金丝雀频道。

不要想当然地认为金丝雀会适合你的情况。先测试。

先决条件

• 安装在Neo4j实例中的APOC插件（必需-- get-schema 用途 apoc.meta.schema).
• 任何兼容MCP的客户端（例如。 VSCode 随着 MCP支持).

⚠️ 已知问题：Neo4j 5.26.18 APOC中有一个错误，导致 get-schema 工具失败。这是固定的 5.26.19 及以上。如果您使用的是5.26.18，请升级。看 #136 了解详情。

启动检查和自适应操作

服务器在启动时执行几次飞行前检查，以确保您的环境配置正确。

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

• 与Neo4j实例的有效连接。
• 执行查询的能力。
• APOC插件的存在。

HTTP模式--跳过验证 在HTTP模式下，会跳过启动验证检查，因为凭据来自每个请求的身份验证标头。服务器在不连接Neo4j的情况下立即启动。

可选要求 如果缺少可选依赖项，服务器将以自适应模式启动。例如，如果未检测到图形数据科学（GDS）库，服务器仍会启动，但会自动禁用依赖于GDS的工具，如 list-gds-procedures。所有其他工具仍然可用。

安装（二进制）

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

1. 下载适用于您的OS/arch的存档。
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

应打印已安装的版本。

运输方式

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

• 工作室 （默认）：桌面客户端（Claude desktop、VSCode）通过stdin/stdout进行标准MCP通信。
• 超文本传输协议：RESTful HTTP服务器，具有基于请求的承载令牌或基于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测试和生产部署的详细说明，请参阅 贡献.md.

配置选项

这 neo4j-mcp-canary 服务器通过环境变量和/或CLI标志进行配置。 CLI标志优先于环境变量。

环境变量

核心连接和行为：

密码执行保障（见 密码执行保障):

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-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 查看带有描述的完整列表。

密码执行保障

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 触发时，该工具返回一个分类错误，该错误命名了配置的限制，并提供特定于工具的补救措施（绑定可变长度模式，添加 WHERE 过滤器，或 LIMIT 为了 read-cypher；减少批量，缩小 MATCH，或使用 apoc.periodic.iterate 为了 write-cypher).呼叫者取消（与超时不同）表面上简洁明了 cancelled 没有补救指导的消息。

计划员估算拒绝

规划者估计保护读取根 EstimatedRows 的 EXPLAIN 在查询运行之前进行计划。因为Neo4j可以折叠 LIMIT 在根估计中，一个合法的 MATCH ... LIMIT 100 查询干净地通过，估计值约为100，而 MATCH 数百万行标签在开始前被拒绝。

身份验证方法（HTTP模式）

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

承载令牌身份验证

承载令牌身份验证实现了与 Neo4j企业版 和 Neo4j光环 使用SSO/Outh/OIDC进行身份管理的环境。这种方法非常适合：

• 使用集中式身份提供程序（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}'

承载令牌从您的身份提供者处获得，并传递给Neo4j进行身份验证。MCP服务器充当传递者，将令牌转发到Neo4j的身份验证系统。

基本认证

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

• Neo4j社区版
• 开发和测试环境
• 无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.
• 架构/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": ... } （以及 z 用于3D）
• 日期/时间/日期时间/本地时间/本地日期时间/持续时间： ISO 8601字符串

弃用的数字 id / startId / endId 标识符是 不 浮出水面-- elementId / startElementId / endElementId 是返回的唯一标识符。

使用指南

金丝雀测试的经验教训，帮助法学硕士（或人类）充分利用 read-cypher:

1. 在数据库中聚合。 count, sum, avg, collect, reduce, percentileCont, stDev，并且类似的缩减缩减缩减为一行，不受行上限的影响。一个类似的查询 UNWIND range(1, 50000) AS i RETURN sum(i) 跑得干净利落；逐行流式传输的相同范围在行上限处被截断。
2. 总是使用 LIMIT 用于探索性查询。 行帽将截断裸露 MATCH 回报；截断包络 hint 字段将告诉调用者添加 LIMIT.更喜欢a 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. EXPLAIN 和 PROFILE 未暴露在 read-cypher. 失控查询保护已由计划器估计保护和执行超时处理。如果您需要一个包含运行时统计信息的概要计划，请使用 write-cypher 随着 PROFILE.
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问题（省略敏感数据）。