Neo4j Canary MCP server

<!-- mcp-name: io.github.neo4j-labs/neo4j-mcp-canary -->

Neo4j MCP Canary — The canary goes first so the rest of us know what's coming

Neo4j MCP Canary is a fast-moving, experimental release of the Neo4j MCP server for customers who want to explore emerging capabilities before they are considered for the official server.

Built on the source of the official Model Context Protocol (MCP) server for Neo4j, this variant is here for exploring potential new capabilities with experimentation.

As it is a labs project, be aware that:

• It is not supported
• It may contain breaking changes between its own releases and with the official Neo4j MCP server
• It should be tested before using

Do not assume the canary will work for your situation. Test first.

Prerequisites

• A running Neo4j database instance; options include Aura, Neo4j Desktop, or self-managed.
• APOC plugin installed in the Neo4j instance (required — get-schema uses apoc.meta.schema).
• Any MCP-compatible client (e.g. VSCode with MCP support).

⚠️ Known Issue: Neo4j 5.26.18 has a bug in APOC that causes the get-schema tool to fail. This is fixed in 5.26.19 and above. If you're on 5.26.18, please upgrade. See #136 for details.

Startup Checks & Adaptive Operation

The server performs several checks to ensure your environment is correctly configured.

STDIO Mode — Mandatory Requirements In STDIO mode, the server verifies the following. If any check fails (e.g. invalid configuration, incorrect credentials, missing APOC), the server will not start:

• A valid connection to your Neo4j instance.
• The ability to execute queries.
• The presence of the APOC plugin.
• Minimum version check for use of Query API to communicate with the datatbase

HTTP Mode — Verification Skipped In HTTP mode, startup verification checks are skipped because credentials come from per-request auth headers. The server starts immediately without connecting to Neo4j. The one exception is Query API mode: its minimum-version check runs at startup in both transport modes, since it only needs an unauthenticated GET and doesn't depend on per-request credentials.

Optional Requirements If an optional dependency is missing, the server starts in adaptive mode. For instance, if the Graph Data Science (GDS) library is not detected, the server still launches but automatically disables GDS-dependent tools such as list-gds-procedures. All other tools remain available.

Installation (Binary)

Releases: Canary MCP releases

1. Download the archive for your OS/arch.
2. Extract and place neo4j-mcp-canary on your PATH.

Mac / Linux:

On Mac, you may be warned the first time you try to run the binary. If so, approve it via System Settings → Privacy & Security.

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

Windows (PowerShell / cmd):

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

Verify the installation:

neo4j-mcp-canary -v

Should print the installed version.

Building from Source

Requires Go 1.26+ (see go.mod).

Build for your current platform with Task:

task build

This produces bin/neo4j-mcp-canary. Without Task, the equivalent is:

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

Cross-compiling for macOS / Linux

Cross-compile by setting GOOS/GOARCH and disabling cgo (the codebase is pure Go, so CGO_ENABLED=0 produces a fully static binary with no runtime dependencies on the target machine):

Shortened. The full README is on GitHub.