🔍⁉️ Neo4j MCP Server

mcp-name: io.github.neo4j-contrib/mcp-neo4j-cypher

🌟 Overview

A Model Context Protocol (MCP) server implementation that provides database interaction and allows graph exploration capabilities through Neo4j. This server enables running Cypher graph queries, analyzing complex domain data, and automatically generating business insights that can be enhanced further with an application's analysis tools.

This MCP server facilitates Text2Cypher workflows like the one detailed below.

• Blue steps are handled by the agent
• Purple by the Cypher or another MCP server
• Green by the user

A user question is input to the process and the output is an answer generated by the agent.

📋 Prerequisites

• Neo4j Database: A running Neo4j instance (Aura or Self-Managed)
• APOC Plugin: The APOC plugin must be installed and enabled on your Neo4j instance. This is required for the get_neo4j_schema tool to function correctly.

🧩 Components

🛠️ Tools

The server offers these core tools:

#### 📊 Query Tools

• read_neo4j_cypher

• Execute Cypher read queries to read data from the database
• Input:
• query (string): The Cypher query to execute
• params (dictionary, optional): Parameters to pass to the Cypher query
• Returns: Query results as JSON serialized array of objects
• Timeout: Read queries are subject to a configurable timeout (default: 30 seconds) to prevent long-running queries from disrupting conversational flow

• write_neo4j_cypher
• Execute updating Cypher queries
• Input:
• query (string): The Cypher update query
• params (dictionary, optional): Parameters to pass to the Cypher query
• Returns: A JSON serialized result summary counter with { nodes_updated: number, relationships_created: number, ... }
• Availability: May be disabled by supplying --read-only as cli flag or NEO4J_READ_ONLY=true environment variable

#### 🕸️ Schema Tools

• get_neo4j_schema
• Get a list of all nodes types in the graph database, their attributes with name, type and relationships to other node types
• Requirement: Requires the APOC plugin to be installed and enabled.
• Input:
• sample_param (integer, optional): Number of nodes to sample for schema analysis. Overrides server default if provided.
• Returns: JSON serialized list of node labels with two dictionaries: one for attributes and one for relationships
• Performance: Uses sampling by default (1000 nodes per label). Reduce number for faster analysis on large databases. To stop sampling, set to -1.

🏷️ Namespacing

The server supports namespacing to allow multiple Neo4j MCP servers to be used simultaneously. When a namespace is provided, all tool names are prefixed with the namespace followed by a hyphen (e.g., mydb-read_neo4j_cypher).

This is useful when you need to connect to multiple Neo4j databases or instances from the same session.

⚙️ Query Configuration

The server provides configuration options to optimize query performance and manage response sizes:

#### ⏱️ Query Timeouts

Configure timeouts for read queries to prevent long-running queries from disrupting conversational flow:

Command Line:

mcp-neo4j-cypher --read-timeout 60  # 60 seconds

Environment Variable:

export NEO4J_READ_TIMEOUT=60

Docker:

docker run -e NEO4J_READ_TIMEOUT=60 mcp-neo4j-cypher:latest

Default: 30 seconds. Read queries that exceed this timeout will be automatically cancelled to maintain responsive interactions with AI models.

#### 📏 Token Limits

Control the maximum size of query responses to prevent overwhelming the AI model:

Command Line:

mcp-neo4j-cypher --token-limit 4000

Environment Variable:

export NEO4J_RESPONSE_TOKEN_LIMIT=4000

Docker:

docker run -e NEO4J_RESPONSE_TOKEN_LIMIT=4000 mcp-neo4j-cypher:latest

When a response exceeds the token limit, it will be automatically truncated to fit within the specified limit using tiktoken. This ensures:

• Consistent Performance: Responses stay within model context limits
• Cost Control: Prevents excessive token usage in AI interactions
• Reliability: Large datasets don't break the conversation flow

Note: Token limits only apply to read_neo4j_cypher responses. Schema queries and write operations return summary information and are not affected.

#### 🔍 Schema Sampling

Control the performance and scope of schema inspection with the sample parameter for the get_neo4j_schema tool:

Command Line:

mcp-neo4j-cypher --sample 1000  # Sample 1000 nodes per label

Environment Variable:

export NEO4J_SCHEMA_SAMPLE_SIZE=1000

Docker:

docker run -e NEO4J_SCHEMA_SAMPLE_SIZE=1000 mcp-neo4j-cypher:latest

The sample parameter controls how many nodes are examined when generating the database schema:

• Default: 1000 nodes per label are sampled for schema analysis
• Performance: Lower values (100, 500) provide faster schema inspection on large databases
• Accuracy: Higher values (5000, 10000) provide more comprehensive schema coverage
• Full Scan: Set to -1 to examine all nodes (can be very slow on large databases)
• Per-Call Override: The get_neo4j_schema tool accepts a sample_param parameter to override the server default

How Sampling Works (via APOC's apoc.meta.schema):

• For each node label, a skip count is calculated: totalNodesForLabel / sample ± 10%
• Every Nth node is examined based on the skip count
• Higher sample numbers result in more nodes being examined
• Results may vary between runs due to random sampling

Example Scenarios:

# Fast schema inspection for large databases
export NEO4J_SCHEMA_SAMPLE_SIZE=100

# Balanced performance and accuracy (default)
export NEO4J_SCHEMA_SAMPLE_SIZE=1000

# Comprehensive schema analysis
export NEO4J_SCHEMA_SAMPLE_SIZE=5000

# Full database scan (use with caution on large databases)
export NEO4J_SCHEMA_SAMPLE_SIZE=-1

Performance Considerations:

• Large Databases: Use lower sample values (100-500) to prevent timeouts
• Development: Higher sample values (1000-5000) for thorough schema understanding
• Production: Balance between performance and schema completeness based on your use case

🏗️ Local Development & Deployment

🐳 Local Docker Development

Build and run locally for testing or remote deployment:

# Build the Docker image with a custom name from your local version of the server
docker build -t mcp-neo4j-cypher:latest .

# Run locally (uses http transport by default for Docker)
docker run -p 8000:8000 \
  -e NEO4J_URI="bolt://host.docker.internal:7687" \
  -e NEO4J_USERNAME="neo4j" \
  -e NEO4J_PASSWORD="your-password" \
  mcp-neo4j-cypher:latest

# Access the server at http://localhost:8000/mcp/

🚀 Transport Modes

The server supports different transport protocols depending on your deployment:

• STDIO (for local development): Standard input/output for Claude Desktop and local tools
• HTTP (for remote deployments): RESTful HTTP for web deployments and microservices
• SSE: Server-Sent Events for legacy web-based deployments

Choose your transport based on use case:

• Local development/Claude Desktop: Use stdio
• Remote deployment: Use http
• Legacy web clients: Use sse

🔒 Security Protection

The server includes comprehensive security protection with secure defaults that protect against common web-based attacks while preserving full MCP functionality when using HTTP transport.

🛡️ DNS Rebinding Protection

TrustedHost Middleware validates Host headers to prevent DNS rebinding attacks:

Secure by Default:

• Only localhost and 127.0.0.1 hosts are allowed by default
• Malicious websites cannot trick browsers into accessing your local server

Environment Variable:

export NEO4J_MCP_SERVER_ALLOWED_HOSTS="example.com,www.example.com"

🌐 CORS Protection

Cross-Origin Resource Sharing (CORS) protection blocks browser-based requests by default:

Environment Variable:

export NEO4J_MCP_SERVER_ALLOW_ORIGINS="https://example.com,https://example.com"

🔧 Complete Security Configuration

Development Setup:

mcp-neo4j-cypher --transport http \
  --allowed-hosts "localhost,127.0.0.1" \
  --allow-origins "http://localhost:3000"

Production Setup:

mcp-neo4j-cypher --transport http \
  --allowed-hosts "example.com,www.example.com" \
  --allow-origins "https://example.com,https://example.com"

🚨 Security Best Practices

For allow_origins:

• Be specific: ["https://example.com", "https://example.com"]