Usage

Tools

Provided tools:

Tool ReadOnly Purpose Notes

get-schema

Yes

Introspect labels, relationship types, property keys

Provide valuable context to the client LLMs.

read-cypher

Yes

Execute arbitrary Cypher® (read mode)

Rejects writes, schema/admin operations, and PROFILE queries.

write-cypher

No

Execute arbitrary Cypher (write mode)

Caution: LLM-generated queries can cause harm. Use only in development environments. Disabled if NEO4J_READ_ONLY=true.

list-gds-procedures

Yes

List GDS procedures available in the instance

Help the client LLM to have better visibility on available GDS procedures.

Readonly mode

Enable readonly mode by setting the NEO4J_READ_ONLY environment variable to true. When enabled, write tools (such as write-cypher) are not exposed to clients.

Configuration

neo4j-mcp requires explicit configuration to connect to your Neo4j instance. Configuration can be provided through environment variables or command-line flags.

Transport modes

The server supports two transport modes:

  • STDIO (default): Traditional standard input/output mode for desktop clients

  • HTTP: Web-based mode for multi-tenant scenarios and web clients

Set the transport mode using the NEO4J_TRANSPORT_MODE environment variable or --neo4j-transport-mode flag.

STDIO mode

In STDIO mode, credentials are provided via environment variables (NEO4J_USERNAME and NEO4J_PASSWORD). The server validates connectivity and APOC availability at startup.

HTTP mode

In HTTP mode, the server operates statelessly and accepts per-request authentication credentials (Bearer Token or Basic Authentication). Do NOT set NEO4J_USERNAME or NEO4J_PASSWORD environment variables in HTTP mode, as credentials come from per-request authentication headers.

Environment variables

The following environment variables are used for configuration:

Variable Description Default

NEO4J_URI

Connection URI (e.g., bolt://localhost:7687)

Required

NEO4J_USERNAME

Neo4j username (STDIO mode only)

Required for STDIO

NEO4J_PASSWORD

Neo4j password (STDIO mode only)

Required for STDIO

NEO4J_DATABASE

Database name

neo4j

NEO4J_READ_ONLY

Set to true to disable write tools

false

NEO4J_TELEMETRY

Set to false to disable telemetry

true

NEO4J_LOG_LEVEL

Log level (see Logging section)

info

NEO4J_LOG_FORMAT

Log output format: text or json

text

NEO4J_SCHEMA_SAMPLE_SIZE

Number of nodes to sample for schema inference

100

NEO4J_MCP_TRANSPORT

This option is deprecated. Please use NEO4J_TRANSPORT_MODE

NEO4J_TRANSPORT_MODE

Transport mode: stdio or http

stdio

HTTP mode configuration

Additional environment variables for HTTP mode:

Variable Description Default

NEO4J_MCP_HTTP_HOST

Server binding address

127.0.0.1

NEO4J_MCP_HTTP_PORT

Server listening port

80 (or 443 with TLS)

NEO4J_MCP_HTTP_ALLOWED_ORIGINS

CORS configuration (comma-separated list, * for all, empty to disable)

empty (disabled)

TLS/HTTPS configuration

Configure TLS for secure HTTPS connections in HTTP mode:

Variable Description Default

NEO4J_MCP_HTTP_TLS_ENABLED

Enable TLS/HTTPS

false

NEO4J_MCP_HTTP_TLS_CERT_FILE

Path to TLS certificate file

Required if TLS enabled

NEO4J_MCP_HTTP_TLS_KEY_FILE

Path to TLS private key file

Required if TLS enabled

TLS configuration enforces TLS 1.2 minimum with secure default cipher suites. When TLS is enabled, the default port changes from 80 to 443. For detailed TLS/HTTPS setup instructions, certificate requirements, and testing procedures, see TLS/HTTPS Setup.

Command-line flags

The following command-line flags are available and take precedence over environment variables:

General flags

Flag Description

--neo4j-uri

Override NEO4J_URI environment variable

--neo4j-username

Override NEO4J_USERNAME environment variable (STDIO mode only)

--neo4j-password

Override NEO4J_PASSWORD environment variable (STDIO mode only)

--neo4j-database

Override NEO4J_DATABASE environment variable

--neo4j-read-only

Override NEO4J_READ_ONLY environment variable

--neo4j-telemetry

Override NEO4J_TELEMETRY environment variable

--neo4j-schema-sample-size

Override NEO4J_SCHEMA_SAMPLE_SIZE environment variable

--neo4j-transport-mode

Override NEO4J_MCP_TRANSPORT (values: stdio or http)

-v, --version

Display version information

HTTP mode flags

Flag Description

--neo4j-http-host

Override NEO4J_MCP_HTTP_HOST environment variable

--neo4j-http-port

Override NEO4J_MCP_HTTP_PORT environment variable

--neo4j-http-tls-enabled

Override NEO4J_MCP_HTTP_TLS_ENABLED environment variable

--neo4j-http-tls-cert-file

Override NEO4J_MCP_HTTP_TLS_CERT_FILE environment variable

--neo4j-http-tls-key-file

Override NEO4J_MCP_HTTP_TLS_KEY_FILE environment variable

Command-line flags take precedence over environment variables.

STDIO mode: The three required connection parameters (URI, username, and password) must be provided via environment variables, command-line flags, or a combination of both.

HTTP mode: Only the URI is required via environment variables or command-line flags. Credentials are provided per-request via Basic Authentication headers.

Usage examples

Quick start (shell)

Minimal snippets to run the server.

STDIO mode:

# STDIO mode
export NEO4J_URI="bolt://localhost:7687"
export NEO4J_USERNAME="neo4j"
export NEO4J_PASSWORD="password"
# Optional: read-only mode
export NEO4J_READ_ONLY="true"
neo4j-mcp

HTTP mode:

# HTTP mode (no username/password env vars)
export NEO4J_URI="bolt://localhost:7687"
export NEO4J_MCP_TRANSPORT="http"
export NEO4J_MCP_HTTP_HOST="127.0.0.1"
export NEO4J_MCP_HTTP_PORT="8080"
neo4j-mcp

STDIO mode examples

Running with environment variables only (as configured in MCP client):

neo4j-mcp

Running with command-line flags:

neo4j-mcp --neo4j-uri bolt://localhost:7687 \
  --neo4j-username neo4j \
  --neo4j-password mypassword \
  --neo4j-database neo4j

Mixing environment variables and flags (flags override env vars):

# Uses NEO4J_URI from environment, but overrides other parameters
neo4j-mcp --neo4j-username admin \
  --neo4j-password adminpass \
  --neo4j-database production

HTTP mode examples

Running HTTP mode with environment variables:

export NEO4J_URI="bolt://localhost:7687"
export NEO4J_MCP_TRANSPORT="http"
export NEO4J_MCP_HTTP_HOST="127.0.0.1"
export NEO4J_MCP_HTTP_PORT="8080"
neo4j-mcp

Running HTTP mode with CORS enabled:

export NEO4J_URI="bolt://localhost:7687"
export NEO4J_MCP_TRANSPORT="http"
export NEO4J_MCP_HTTP_ALLOWED_ORIGINS="http://localhost:3000,https://app.example.com"
neo4j-mcp

Running HTTP mode with TLS enabled:

neo4j-mcp --neo4j-uri bolt://localhost:7687 \
  --neo4j-transport-mode http \
  --neo4j-http-tls-enabled true \
  --neo4j-http-tls-cert-file /path/to/cert.pem \
  --neo4j-http-tls-key-file /path/to/key.pem \
  --neo4j-http-port 8443

In HTTP mode, authentication credentials are provided per-request via Basic Authentication headers, not through environment variables or command-line flags. Each HTTP request must include an Authorization header with Base64-encoded credentials in the format Basic <base64(username:password)>.

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 Single Sign-On (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

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

Which Authentication Method Should I Use?

Use Bearer Token when:

  • You’re using Neo4j Enterprise Edition or Aura with SSO/OIDC/OAuth configured

  • You want to integrate with your organization’s identity provider

  • You need to support OAuth 2.0 flows

Use Basic Auth when:

  • You’re using traditional username/password authentication

  • You’re using Neo4j Community Edition

  • You have direct database credentials

Logging

neo4j-mcp implements a structured logging system using the log levels defined in the MCP specification. Logging can be configured using environment variables to control the verbosity and output format.

Log levels

The following log levels are supported, as defined by the MCP specification (from most to least verbose):

  • debug - Detailed diagnostic information

  • info - General informational messages (default)

  • notice - Normal but significant events

  • warning - Warning messages

  • error - Error messages

  • critical - Critical conditions

  • alert - Action must be taken immediately

  • emergency - System is unusable

Set the log level using the NEO4J_LOG_LEVEL environment variable. The log level is set at startup and remains fixed for the lifetime of the server process.

Log formats

Two output formats are available:

  • text (default) - Human-readable text format

  • json - Structured JSON format for log parsing and analysis

Set the log format using the NEO4J_LOG_FORMAT environment variable.

Security features

The logging system automatically redacts sensitive information including:

  • Passwords

  • Authentication tokens

  • Connection credentials

This ensures that sensitive data does not leak into log files.

Configuration examples

Enable debug logging with text output:

{
  "mcpServers": {
    "neo4j-mcp": {
      "command": "neo4j-mcp",
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_LOG_LEVEL": "debug",
        "NEO4J_LOG_FORMAT": "text"
      }
    }
  }
}

Enable JSON logging for automated parsing:

{
  "mcpServers": {
    "neo4j-mcp": {
      "command": "neo4j-mcp",
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_LOG_LEVEL": "info",
        "NEO4J_LOG_FORMAT": "json"
      }
    }
  }
}

Examples for natural language prompts

Here 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 considerations

  • Use a restricted Neo4j user for exploration.

  • Review the generated Cypher queries before executing them in production databases.

Troubleshooting authentication

Bearer Token Issues

401 Unauthorized - Token not accepted

  • Verify your Neo4j instance is Enterprise Edition or Aura with OAuth/SSO configured

  • Community Edition does not support bearer token authentication - use Basic Auth instead

  • Confirm the token hasn’t expired - bearer tokens typically have short lifespans (15-60 minutes)

  • Check with your identity provider to ensure the token is valid

Invalid token format

  • Ensure the header format is exactly: Authorization: Bearer YOUR_TOKEN

  • No extra spaces before or after "Bearer"

  • Token should not be base64-encoded (unlike Basic Auth)

Neo4j rejects valid token

  • Verify your Neo4j instance is configured to accept tokens from your identity provider

  • Check Neo4j server logs for specific authentication errors

  • Confirm the token issuer matches Neo4j’s OAuth configuration

Basic Auth Issues

401 Unauthorized - Credentials not accepted

  • Verify username and password are correct

  • Check that credentials are properly base64 encoded: echo -n "user:pass" | base64

  • Ensure the authorization header format is: Authorization: Basic BASE64_STRING

Empty credentials error

  • Both username and password must be non-empty

  • The base64 string must decode to username:password format with both parts present

General Issues

No authentication header provided

  • HTTP mode requires authentication on every request

  • Ensure your MCP client configuration includes the Authorization header

Connection refused / Cannot reach server

  • Verify the Neo4j MCP server is running in HTTP mode

  • Check the server is listening on the correct host:port

  • Confirm firewall rules allow connections to the MCP server port

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".