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.

You are welcome to contribute — we are always open to new ideas, especially in this canary channel.

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 pre-flight checks at startup 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.

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: https://github.com/neo4j-labs/neo4j-mcp-canary/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.25.3+ (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):

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

To stamp a version into the binary (-v / --version), pass an ldflags override — this is what the release pipeline does for tagged builds:

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

Without it, Version defaults to "development", which also disables telemetry regardless of NEO4J_TELEMETRY (see Telemetry).

Official multi-platform release archives (including Windows) are built by GoReleaser per .goreleaser.yaml — see Installation (Binary) to download those instead of building locally.

Transport Modes

The Neo4j MCP Canary server supports two transport modes:

• STDIO (default): Standard MCP communication via stdin/stdout for desktop clients (Claude Desktop, VSCode).
• HTTP: RESTful HTTP server with per-request Bearer token or Basic Authentication for web-based clients and multi-tenant scenarios. Where the standard Authorization header cannot be used, a custom header name can be configured.

Key Differences

See the Client Setup Guide for configuration instructions for both modes.

Unauthenticated MCP Client Requests

By default, there are four requests a MCP client can send without authentication when using HTTP(S) transport. Some integrations (AWS AgentCore, AWS Gateway, etc.) rely on this as an initial health-check mechanism:

• ping
• initialize
• tools/list
• notifications/initialize

If you do not need these, enforce authentication individually via the variables below.

TLS/HTTPS Configuration

When using HTTP transport, enable TLS for secure communication via the variables below.

Security Configuration

• Minimum TLS Version: TLS 1.2 (TLS 1.3 negotiated when available)
• Cipher Suites: Go's secure default cipher suites
• Default Port: Automatically uses 443 when TLS is enabled

Example

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

Production Usage: use certificates from a trusted CA (Let's Encrypt, your organisation's CA, etc.) for production deployments.