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_MCP_TRANSPORT 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 Basic Authentication credentials. Do NOT set NEO4J_USERNAME or NEO4J_PASSWORD environment variables in HTTP mode, as credentials come from per-request Basic Auth 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

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.

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

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.

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