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)

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.