Introduction

Neo4j MCP gives AI assistants and LLM-powered tools direct, structured access to your Neo4j graph database. By implementing the Model Context Protocol (MCP), it acts as a bridge between any MCP-compatible client, such as Claude, Cursor, or VS Code with MCP support, and your Neo4j instance.

Neo4j MCP is intended for:

Developers building or prototyping graph-backed AI applications who want to query Neo4j conversationally during development.
Data scientists and analysts who want to explore graph data without deep Cypher^® expertise.
Platform and infrastructure teams deploying shared AI tooling that needs structured, auditable access to a Neo4j instance.
AI application builders integrating Neo4j as a knowledge source or reasoning backend in multi-agent systems.

Neo4j MCP enables AI agents to:

Explore your graph schema - discover node labels, relationship types, and property keys so the AI can reason about your data model without prior knowledge of it.
Run Cypher queries - execute, read, and write queries against your database in response to natural language prompts.
Inspect and analyze data - retrieve nodes, relationships, and paths to answer questions, generate summaries, or feed data to other workflows.

Prerequisites

A running Neo4j database instance. Options include Aura, neo4j-desktop or self-managed.
The APOC plugin installed in the Neo4j instance.
Any MCP-compatible client, e.g. VSCode with MCP support.

Security considerations

Use a restricted Neo4j user for exploring the database. To avoid undesirable operations or even data loss, it is also advisable to review Cypher queries generated with MCP before executing them against a database, especially when it is a production database.

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

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