Neo4j MCP Canary
Neo4j MCP Canary is hosted in Neo4j labs as, although it is based on the Official Model Context Protocol (MCP) server for Neo4j, this variant is here for exploriing potential new capabilities with experimentations.
Neo4j MCP Canary is mostly compatibility with the command line arguements and environmental variables used by the Official Model Context Protocol (MCP) server but do not make assumptions and always check.
You are welcome to contribute - we are always open to new ideas , even more so with the Canary version.
Prerequisites
⚠️ Known Issue: Neo4j version 5.26.18 has a bug in APOC that causes the get-schema tool to fail. This issue is fixed in version 5.26.19 and above. If you're using 5.26.18, please upgrade to 5.26.19 or later. 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 core requirements. If any of these checks fail (e.g., due to an invalid configuration, incorrect credentials, or a missing APOC installation), 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 Basic Auth headers. The server starts immediately without connecting to Neo4j at startup.
Optional Requirements
If an optional dependency is missing, the server will start in an adaptive mode. For instance, if the Graph Data Science (GDS) library is not detected in your Neo4j installation, the server will still launch but will automatically disable all GDS-related tools, such as list-gds-procedures. All other tools will remain available.
Installation (Binary)
Releases: https://github.com/neo4j-labs/neo4j-mcp-canary/releases
- Download the archive for your OS/arch.
- Extract and place
neo4j-mcp in a directory present in your PATH variables (see examples below).
Mac / Linux:
On Mac, you may be warned the first time you try and run the Mac binary. If that happens you may need to approve it using Settings -> Privacy & Security
chmod +x neo4j-mcp
sudo mv neo4j-mcp /usr/local/bin/
Windows (PowerShell / cmd):
move neo4j-mcp.exe C:\Windows\System32
Verify the neo4j-mcp installation:
neo4j-mcp -v
Should print the installed version.
Transport Modes
The Neo4j MCP 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 scenario.
In case where the standard HTTP header "Authorization" can't be used, it's possible to configure a custom HTTP header for this scope.
Key Differences
| Aspect |
STDIO |
HTTP |
| Startup Verification |
Required - server verifies APOC, connectivity, queries |
Skipped - server starts immediately |
| Credentials |
Set via environment variables |
Per-request via Bearer token or Basic Auth headers |
| Telemetry |
Collects Neo4j version, edition, Cypher version at startup |
Reports "unknown-http-mode" - actual version info not available at startup |
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 needing authentication when using HTTP(S) transportation. Some integrations (such as AWS AgentCore, AWS Gateway ) rely on this as an initial health check mechanism
The requests are
- Ping
- Initialize
- Tools/List
- Notifications/Initialize
If you do not need these, you can enforce authentication requirements for each by using the relevant environmental variable or command line argument
Environment Variables
NEO4J_HTTP_ALLOW_UNAUTHENTICATED_PING - Allow unauthenticated ping health checks (default: true)
NEO4J_HTTP_ALLOW_UNAUTHENTICATED_TOOLS_LIST Allow unauthenticated tool listing (default: true)
NEO4J_HTTP_ALLOW_UNAUTHENTICATED_INITIALIZE Allow unauthenticated initialize (default: true)
NEO4J_HTTP_ALLOW_UNAUTHENTICATED_NOTIFICATIONS_INITIALIZE Allow unauthenticated notification initialize (default: true)
TLS/HTTPS Configuration
When using HTTP transport mode, you can enable TLS/HTTPS for secure communication:
Environment Variables
NEO4J_MCP_HTTP_TLS_ENABLED - Enable TLS/HTTPS: true or false (default: false)
NEO4J_MCP_HTTP_TLS_CERT_FILE - Path to TLS certificate file (required when TLS is enabled)
NEO4J_MCP_HTTP_TLS_KEY_FILE - Path to TLS private key file (required when TLS is enabled)
NEO4J_MCP_HTTP_PORT - HTTP server port (default: 443 when TLS enabled, 80 when TLS disabled)
NEO4J_HTTP_AUTH_HEADER_NAME - Name of the HTTP header to read auth credentials from (default: Authorization)
Security Configuration
- Minimum TLS Version: TLS 1.2 (allows TLS 1.3 negotiation)
- Cipher Suites: Uses Go's secure default cipher suites
- Default Port: Automatically uses port 443 when TLS is enabled (standard HTTPS port)
Example Configuration
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
# Server will listen on https://127.0.0.1:443 by default
Production Usage: Use certificates from a trusted Certificate Authority (e.g., Let's Encrypt, or your organisation) for production deployments.
For detailed instructions on certificate generation, testing TLS, and production deployment, see CONTRIBUTING.md.
Configuration Options
The neo4j-mcp server can be configured using environment variables or CLI flags. CLI flags take precedence over environment variables.
Environment Variables
See the Client Setup Guide for configuration examples.
CLI Flags
You can override any environment variable using CLI flags:
neo4j-mcp --neo4j-uri "bolt://localhost:7687" \
--neo4j-username "neo4j" \
--neo4j-password "password" \
--neo4j-database "neo4j" \
--neo4j-read-only false \
--neo4j-telemetry true
Available flags:
--neo4j-uri - Neo4j connection URI (overrides NEO4J_URI)
--neo4j-username - Database username (overrides NEO4J_USERNAME)
--neo4j-password - Database password (overrides NEO4J_PASSWORD)
--neo4j-database - Database name (overrides NEO4J_DATABASE)
--neo4j-read-only - Enable read-only mode: true or false (overrides NEO4J_READ_ONLY)
--neo4j-telemetry - Enable telemetry: true or false (overrides NEO4J_TELEMETRY)
--neo4j-schema-sample-size - Modify the sample size used to infer the Neo4j schema
--neo4j-transport-mode - Transport mode: stdio or http (overrides NEO4J_TRANSPORT_MODE)
--neo4j-http-host - HTTP server host (overrides NEO4J_MCP_HTTP_HOST)
--neo4j-http-port - HTTP server port (overrides NEO4J_MCP_HTTP_PORT)
--neo4j-http-tls-enabled - Enable TLS/HTTPS: true or false (overrides NEO4J_MCP_HTTP_TLS_ENABLED)
--neo4j-http-tls-cert-file - Path to TLS certificate file (overrides NEO4J_MCP_HTTP_TLS_CERT_FILE)
--neo4j-http-tls-key-file - Path to TLS private key file (overrides NEO4J_MCP_HTTP_TLS_KEY_FILE)
--neo4j-http-auth-header-name - Name of the HTTP header to read auth credentials from (overrides NEO4J_AUTH_HEADER_NAME)
--neo4j-http-allow-unauthenticated-ping - Allow unauthenticated ping health checks: true or false (overrides NEO4J_HTTP_ALLOW_UNAUTHENTICATED_PING)
--neo4j-http-allow-unauthenticated-tools-list Allow unauthenticated tools list: true or false (overrides NEO4J_HTTP_ALLOW_UNAUTHENTICATED_TOOLS_LIST)
--neo4j-http-allow-unauthenticated-initialize Allow unauthenticated tools list: true or false (overrides NEO4J_HTTP_ALLOW_UNAUTHENTICATED_INITIALIZE)
--neo4j-http-allow-unauthenticated-notifications-initialize Allow unauthenticated tools list: true or false (overrides NEO4J_HTTP_ALLOW_UNAUTHENTICATED_NOTIFICATIONS_INITIALIZE)
Use neo4j-mcp --help to see all available options.
Authentication Methods (HTTP Mode)
When using HTTP transport mode, the Neo4j MCP server supports two authentication methods to accommodate different deployment scenarios:
Bearer Token Authentication
Bearer token authentication enables seamless integration with Neo4j Enterprise Edition and Neo4j Aura environments that use SSO/OAuth/OIDC for identity management. This method is ideal for:
- Enterprise deployments with centralized identity providers (Okta, Azure AD, etc.)
- Neo4j Aura databases configured with SSO
- Organizations requiring OAuth 2.0 compliance
- Multi-factor authentication scenarios
Example:
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}'
The bearer token is obtained from your identity provider and passed to Neo4j for authentication. The MCP server acts as a pass-through, forwarding the token to Neo4j's authentication system.
Basic Authentication
Traditional username/password authentication suitable for:
- Neo4j Community Edition
- Development and testing environments
- Direct database credentials without SSO
Example:
curl -X POST http://localhost:8080/mcp \
-u neo4j:password \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
Client Configuration
To configure MCP clients (VSCode, Claude Desktop, etc.) to use the Neo4j MCP server, see:
📘 Client Setup Guide – Complete configuration for STDIO and HTTP modes
Provided tools:
| Tool |
ReadOnly |
Purpose |
Notes |
get-schema |
true |
Introspect labels, relationship types, property keys |
Provide valuable context to the client LLMs. |
read-cypher |
true |
Execute arbitrary Cypher (read mode) |
Rejects writes, schema/admin operations, and PROFILE queries. Use write-cypher instead. |
write-cypher |
false |
Execute arbitrary Cypher (write mode) |
Caution: LLM-generated queries could cause harm. Use only in development environments. Disabled if NEO4J_READ_ONLY=true. |
list-gds-procedures |
true |
List GDS procedures available in the Neo4j instance |
Help the client LLM to have a better visibility on the GDS procedures available |
Readonly mode flag
Enable readonly mode by setting the NEO4J_READ_ONLY environment variable to true (for example, "NEO4J_READ_ONLY": "true"). Accepted values are true or false (default: false).
You can also override this setting using the --neo4j-read-only CLI flag:
neo4j-mcp --neo4j-uri "bolt://localhost:7687" --neo4j-username "neo4j" --neo4j-password "password" --neo4j-read-only true
When enabled, write tools (for example, write-cypher) are not exposed to clients.
Query Classification
The read-cypher tool performs an extra round-trip to the Neo4j database to guarantee read-only operations.
Important notes:
- Write operations:
CREATE, MERGE, DELETE, SET, etc., are treated as non-read queries.
- Admin queries: Commands like
SHOW USERS, SHOW DATABASES, etc., are treated as non-read queries and must use write-cypher instead.
- Profile queries:
EXPLAIN PROFILE queries are treated as non-read queries, even if the underlying statement is read-only.
- Schema operations:
CREATE INDEX, DROP CONSTRAINT, etc., are treated as non-read queries.
Example Natural Language Prompts
Below are some example prompts you can try in Copilot or any other MCP client:
- "What does my Neo4j instance contain? List all node labels, relationship types, and property keys."
- "Find all Person nodes and their relationships in my Neo4j instance."
- "Create a new User node with a name 'John' in my Neo4j instance."
Security tips:
- Use a restricted Neo4j user for exploration.
- Review generated Cypher before executing in production databases.
Logging
The server uses structured logging with support for multiple log levels and output formats.
Configuration
Log Level (NEO4J_LOG_LEVEL, default: info)
Controls the verbosity of log output. Supports all MCP log levels: debug, info, notice, warning, error, critical, alert, emergency.
Log Format (NEO4J_LOG_FORMAT, default: text)
Controls the output format:
text - Human-readable text format (default)
json - Structured JSON format (useful for log aggregation)
Telemetry
By default, neo4j-mcp collects anonymous usage data to help us improve the product.
This includes information like the tools being used, the operating system, and CPU architecture.
We do not collect any personal or sensitive information.
To disable telemetry, set the NEO4J_TELEMETRY environment variable to "false". Accepted values are true or false (default: true).
You can also use the --neo4j-telemetry CLI flag to override this setting.
Documentation
📘 Client Setup Guide – Configure VSCode, Claude Desktop, and other MCP clients (STDIO and HTTP modes)
📚 Contributing Guide – Contribution workflow, development environment, mocks & testing
Issues / feedback: open a GitHub issue with reproduction details (omit sensitive data).