Configuration reference

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). Also see Authentication → Bearer token authentication and Authentication → Basic authentication.

Do NOT set NEO4J_USERNAME or NEO4J_PASSWORD environment variables in HTTP mode, as credentials come from per-request authentication headers.

General configuration

The following environment variables and equivalent command-line flags are general configuration options:

Variable Equivalent command-line flag Description Default

NEO4J_URI

--neo4j-uri

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

Required

NEO4J_DATABASE

--neo4j-database

Database name

neo4j

NEO4J_READ_ONLY

--neo4j-read-only

Set to true to disable write tools (see Readonly mode)

false

NEO4J_TELEMETRY

--neo4j-telemetry

Set to false to disable telemetry (see Telemetry)

true

NEO4J_LOG_LEVEL

--neo4j-log-level

Log level (see Logging)

info

NEO4J_LOG_FORMAT

--neo4j-log-format

Log output format: text or json (see Log formats)

text

NEO4J_SCHEMA_SAMPLE_SIZE

--neo4j-schema-sample-size

Number of nodes to sample for schema inference

100

NEO4J_MCP_TRANSPORT

--neo4j-mcp-transport

This option is deprecated. Please use NEO4J_TRANSPORT_MODE

NEO4J_TRANSPORT_MODE

--neo4j-transport-mode

Transport mode: stdio or http

stdio

NEO4J_HTTP_ALLOW_UNAUTHENTICATED

--neo4j-http-allowed-unauthenticated

Exclude the ping method from authentication requirements to account for integrations (such as AWS AgentCore) which rely on pings prior to initialization

false

STDIO configuration

Additional environment variables and equivalent command-line flags for STDIO mode:

Variable Equivalent command-line flag Description Default

NEO4J_USERNAME

--neo4j-username

Neo4j username (STDIO mode only)

Required for STDIO

NEO4J_PASSWORD

--neo4j-password

Neo4j password (STDIO mode only)

Required for STDIO

HTTP configuration

Additional environment variables and equivalent command-line flags for HTTP mode:

Variable Equivalent command-line flag Description Default

NEO4J_MCP_HTTP_HOST

--neo4j-http-host

Server binding address

127.0.0.1

NEO4J_MCP_HTTP_PORT

--neo4j-http-port

Server listening port

80 (or 443 with TLS)

NEO4J_MCP_HTTP_ALLOWED_ORIGINS

--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 Equivalent command-line flag Description Default

NEO4J_MCP_HTTP_TLS_ENABLED

--neo4j-http-tls-enabled

Enable TLS/HTTPS

false

NEO4J_MCP_HTTP_TLS_CERT_FILE

--neo4j-http-tls-cert-file

Path to TLS certificate file

Required if TLS enabled

NEO4J_MCP_HTTP_TLS_KEY_FILE

--neo4j-http-tls-key-file

Path to TLS private key file

Required if TLS enabled

Command-line flags take precedence over environment variables.