Neo4j MCP Server
Allows running Cypher queries and exploring graph data on a Neo4j database.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Neo4j MCP Server show me the schema of the graph database"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
πβοΈ Neo4j MCP Server
π 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.

Related MCP server: Neo4j MCP Server
π§© Components
π οΈ Tools
The server offers these core tools:
π Query Tools
read_neo4j_cypherExecute Cypher read queries to read data from the database
Input:
query(string): The Cypher query to executeparams(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_cypherExecute updating Cypher queries
Input:
query(string): The Cypher update queryparams(dictionary, optional): Parameters to pass to the Cypher query
Returns: A JSON serialized result summary counter with
{ nodes_updated: number, relationships_created: number, ... }
πΈοΈ Schema Tools
get_neo4j_schemaGet a list of all nodes types in the graph database, their attributes with name, type and relationships to other node types
No input required
Returns: JSON serialized list of node labels with two dictionaries: one for attributes and one for relationships
π·οΈ 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 secondsEnvironment Variable:
export NEO4J_READ_TIMEOUT=60Docker:
docker run -e NEO4J_READ_TIMEOUT=60 mcp-neo4j-cypher:latestDefault: 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 4000Environment Variable:
export NEO4J_RESPONSE_TOKEN_LIMIT=4000Docker:
docker run -e NEO4J_RESPONSE_TOKEN_LIMIT=4000 mcp-neo4j-cypher:latestWhen 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.
ποΈ 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/api/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
stdioRemote deployment: Use
httpLegacy 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
localhostand127.0.0.1hosts are allowed by defaultMalicious 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"]Never use
"*"in production with credentialsUse HTTPS origins in production
For allowed_hosts:
Include your actual domain:
["example.com", "www.example.com"]Include localhost only for development
Never use
"*"unless you understand the risks
π§ Usage with Claude Desktop
Using DXT
Download the latest .dxt file from the releases page and install it with your MCP client.
πΎ Released Package
Can be found on PyPi https://pypi.org/project/mcp-neo4j-cypher/
Add the server to your claude_desktop_config.json with the database connection configuration through environment variables. You may also specify the transport method, namespace and other config variables with cli arguments or environment variables.
{
"mcpServers": {
"neo4j-database": {
"command": "uvx",
"args": [ "mcp-neo4j-cypher@0.4.0", "--transport", "stdio" ],
"env": {
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_USERNAME": "neo4j",
"NEO4J_PASSWORD": "<your-password>",
"NEO4J_DATABASE": "neo4j"
}
}
}
}π HTTP Transport Configuration
For custom HTTP configurations with security middleware:
# Complete HTTP configuration with security
mcp-neo4j-cypher --transport http \
--server-host 127.0.0.1 \
--server-port 8080 \
--server-path /api/mcp/ \
--allowed-hosts "localhost,127.0.0.1,example.com" \
--allow-origins "https://yourapp.com"
# Using environment variables
export NEO4J_TRANSPORT=http
export NEO4J_MCP_SERVER_HOST=127.0.0.1
export NEO4J_MCP_SERVER_PORT=8080
export NEO4J_MCP_SERVER_PATH=/api/mcp/
export NEO4J_MCP_SERVER_ALLOWED_HOSTS="localhost,127.0.0.1,example.com"
export NEO4J_MCP_SERVER_ALLOW_ORIGINS="https://yourapp.com"
mcp-neo4j-cypherMultiple Database Example
Here's an example of connecting to multiple Neo4j databases using namespaces:
{
"mcpServers": {
"movies-neo4j": {
"command": "uvx",
"args": ["mcp-neo4j-cypher@0.4.0", "--namespace", "movies"],
"env": {
"NEO4J_URI": "neo4j+s://demo.neo4jlabs.com",
"NEO4J_USERNAME": "recommendations",
"NEO4J_PASSWORD": "recommendations",
"NEO4J_DATABASE": "recommendations"
}
},
"local-neo4j": {
"command": "uvx",
"args": ["mcp-neo4j-cypher@0.4.0"],
"env": {
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_USERNAME": "neo4j",
"NEO4J_PASSWORD": "password",
"NEO4J_DATABASE": "neo4j",
"NEO4J_NAMESPACE": "local"
}
}
}
}In this setup:
The movies database tools will be prefixed with
movies-(e.g.,movies-read_neo4j_cypher)The local database tools will be prefixed with
local-(e.g.,local-get_neo4j_schema)
Syntax with --db-url, --username, --password, --read-timeout and other command line arguments is still supported but environment variables are preferred:
"mcpServers": {
"neo4j": {
"command": "uvx",
"args": [
"mcp-neo4j-cypher@0.4.0",
"--db-url",
"bolt://localhost",
"--username",
"neo4j",
"--password",
"<your-password>",
"--namespace",
"mydb",
"--transport",
"sse",
"--server-host",
"127.0.0.1",
"--server-port",
"8000"
"--server-path",
"/api/mcp/"
]
}
}π³ Using with Docker
Here we use the Docker Hub hosted Cypher MCP server image with stdio transport for use with Claude Desktop.
Config details:
-i: Interactive mode - keeps STDIN open for stdio transport communication--rm: Automatically remove container when it exits (cleanup)-p 8000:8000: Port mapping - maps host port 8000 to container port 8000NEO4J_TRANSPORT=stdio: Uses stdio transport for Claude Desktop compatibilityNEO4J_NAMESPACE=neo4j: Prefixes tools with "neo4j-" (e.g.,neo4j-read_neo4j_cypher)NEO4J_URI=bolt://host.docker.internal:7687: Allows Docker container to connect to Neo4j running on host machine
{
"mcpServers": {
"neo4j": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-p",
"8000:8000",
"-e", "NEO4J_URI=bolt://host.docker.internal:7687",
"-e", "NEO4J_USERNAME=neo4j",
"-e", "NEO4J_PASSWORD=password",
"-e", "NEO4J_NAMESPACE=neo4j",
"-e", "NEO4J_TRANSPORT=stdio",
"mcp/neo4j-cypher:latest"
]
}
}
}π³ Docker Deployment
The Neo4j MCP server can be deployed using Docker for remote deployments. Docker deployment should use HTTP transport for web accessibility. In order to integrate this deployment with applications like Claude Desktop, you will have to use a proxy in your MCP configuration such as mcp-remote.
π¦ Using Your Built Image
After building locally with docker build -t mcp-neo4j-cypher:latest .:
# Run with http transport (default for Docker)
docker run --rm -p 8000:8000 \
-e NEO4J_URI="bolt://host.docker.internal:7687" \
-e NEO4J_USERNAME="neo4j" \
-e NEO4J_PASSWORD="password" \
-e NEO4J_DATABASE="neo4j" \
-e NEO4J_TRANSPORT="http" \
-e NEO4J_MCP_SERVER_HOST="0.0.0.0" \
-e NEO4J_MCP_SERVER_PORT="8000" \
-e NEO4J_MCP_SERVER_PATH="/mcp/" \
mcp/neo4j-cypher:latest
# Run with security middleware for production
docker run --rm -p 8000:8000 \
-e NEO4J_URI="bolt://host.docker.internal:7687" \
-e NEO4J_USERNAME="neo4j" \
-e NEO4J_PASSWORD="password" \
-e NEO4J_DATABASE="neo4j" \
-e NEO4J_TRANSPORT="http" \
-e NEO4J_MCP_SERVER_HOST="0.0.0.0" \
-e NEO4J_MCP_SERVER_PORT="8000" \
-e NEO4J_MCP_SERVER_PATH="/mcp/" \
-e NEO4J_MCP_SERVER_ALLOWED_HOSTS="example.com,www.example.com" \
-e NEO4J_MCP_SERVER_ALLOW_ORIGINS="https://example.com" \
mcp/neo4j-cypher:latestπ§ Environment Variables
Variable | Default | Description |
|
| Neo4j connection URI |
|
| Neo4j username |
|
| Neo4j password |
|
| Neo4j database name |
|
| Transport protocol ( |
| (empty) | Tool namespace prefix |
|
| Host to bind to |
|
| Port for HTTP/SSE transport |
|
| Path for accessing MCP server |
| (empty - secure by default) | Comma-separated list of allowed CORS origins |
|
| Comma-separated list of allowed hosts (DNS rebinding protection) |
| (none) | Maximum tokens for read query responses |
|
| Timeout in seconds for read queries |
π SSE Transport for Legacy Web Access
When using SSE transport (for legacy web clients), the server exposes an HTTP endpoint:
# Start the server with SSE transport
docker run -d -p 8000:8000 \
-e NEO4J_URI="neo4j+s://demo.neo4jlabs.com" \
-e NEO4J_USERNAME="recommendations" \
-e NEO4J_PASSWORD="recommendations" \
-e NEO4J_DATABASE="recommendations" \
-e NEO4J_TRANSPORT="sse" \
-e NEO4J_MCP_SERVER_HOST="0.0.0.0" \
-e NEO4J_MCP_SERVER_PORT="8000" \
--name neo4j-mcp-server \
mcp-neo4j-cypher:latest
# Test the SSE endpoint
curl http://localhost:8000/sse
# Use with MCP Inspector
npx @modelcontextprotocol/inspector http://localhost:8000/sseπ³ Docker Compose
For more complex deployments, you may use Docker Compose:
version: '3.8'
services:
# Deploy Neo4j Database (optional)
neo4j:
image: neo4j:5.26.1 # or another version
environment:
- NEO4J_AUTH=neo4j/password
- NEO4J_PLUGINS=["apoc"]
ports:
- '7474:7474' # HTTP
- '7687:7687' # Bolt
volumes:
- neo4j_data:/data
# Deploy Cypher MCP Server
mcp-neo4j-cypher-server:
image: mcp/neo4j-cypher:latest
ports:
- '8000:8000'
environment:
- NEO4J_URI=bolt://host.docker.internal:7687
- NEO4J_USERNAME=neo4j
- NEO4J_PASSWORD=password
- NEO4J_DATABASE=neo4j
- NEO4J_TRANSPORT=http
- NEO4J_MCP_SERVER_HOST=0.0.0.0 # must be 0.0.0.0 for sse or http transport in Docker
- NEO4J_MCP_SERVER_PORT=8000
- NEO4J_MCP_SERVER_PATH=/api/mcp/
- NEO4J_NAMESPACE=local
depends_on:
- neo4j
volumes:
neo4j_data:Run with: docker-compose up -d
π Claude Desktop Integration with Docker
For Claude Desktop integration with a Dockerized server using http transport:
{
"mcpServers": {
"neo4j-docker": {
"command": "npx",
"args": ["-y", "mcp-remote@latest", "http://localhost:8000/api/mcp/"]
}
}
}Note: First start your Docker container with HTTP transport, then Claude Desktop can connect to it via the HTTP endpoint and proxy server like mcp-remote.
π Development
π¦ Prerequisites
Install
uv:
# Using pip
pip install uv
# Using Homebrew on macOS
brew install uv
# Using cargo (Rust package manager)
cargo install uvClone the repository and set up development environment:
# Clone the repository
git clone https://github.com/neo4j-contrib/mcp-neo4j.git
cd mcp-neo4j-cypher
# Create and activate virtual environment using uv
uv venv
source .venv/bin/activate # On Unix/macOS
.venv\Scripts\activate # On Windows
# Install dependencies including dev dependencies
uv pip install -e ".[dev]"Run Integration Tests
./tests.shπ§ Development Configuration
For development with Claude Desktop using the local source:
{
"mcpServers": {
"neo4j-dev": {
"command": "uv",
"args": ["--directory", "/path/to/mcp-neo4j-cypher", "run", "mcp-neo4j-cypher", "--transport", "stdio", "--namespace", "dev"],
"env": {
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_USERNAME": "neo4j",
"NEO4J_PASSWORD": "<your-password>",
"NEO4J_DATABASE": "neo4j"
}
}
}
}Replace /path/to/mcp-neo4j-cypher with your actual project directory path.
π License
This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
Available Tools
3 toolsget_neo4j_schemaGet Neo4j SchemaARead-onlyIdempotent
List all nodes, their attributes and their relationships to other nodes in the neo4j database. This requires that the APOC plugin is installed and enabled.
Inputs: no named parameters.
read_neo4j_cypherRead Neo4j CypherBRead-onlyIdempotent
Execute a read Cypher query on the neo4j database.
Inputs: query (required), params.
write_neo4j_cypherWrite Neo4j CypherADestructive
Execute a write Cypher query on the neo4j database.
Inputs: query (required), params.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose: write_neo4j_cypher for mutations, read_neo4j_cypher for queries, and get_neo4j_schema for metadata. There is no overlap or ambiguity between them.
All tools follow a consistent verb_neo4j_noun pattern (write/read/get). The naming is predictable and the verb clearly indicates the operation type.
With three tools, the server is well-scoped for its purpose: read, write, and schema introspection. Each tool covers an essential need without redundancy.
The surface covers the core operations for a Neo4j MCP server: fetching schema, executing read queries, and executing write queries. Since write Cypher can handle create, update, and delete, there are no major gaps.
Related MCP Connectors
A Model Context Protocol server for Wix AI tools
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yoβ¦
The Grafbase MCP server sits in front of a GraphQL API and exposes an MCP protocol-compliant interface that allows AI agents and LLMs to explore and query GraphQL APIs using natural language. It provides tools to search schemas, introspect types and fields, and execute GraphQL queries while minimizing context bloat by returning only relevant schema subsets, with built-in support for authentication, authorization, and configurable access control.
A private graph database you query in plain English or Cypher. Hosted, nothing to install.
Related MCP Servers
- AlicenseBqualityDmaintenanceA Model Context Protocol server implementation that enables LLMs to interact with NebulaGraph database for graph exploration, supporting schema understanding, queries, and graph algorithms.529Apache 2.0
- AlicenseBqualityDmaintenanceAn implementation for managing Neo4j graph database operations through the Model Context Protocol, enabling users to execute Cypher queries against their Neo4j database via AI assistants like Cursor and Claude Desktop.118 npm4ISC

Memgraph MCP Serverofficial
AlicenseCqualityNot gradedmaintenanceA lightweight server implementation of the Model Context Protocol that connects Memgraph database with LLMs, allowing users to interact with graph databases through natural language.125MIT- AlicenseAqualityDmaintenanceAn MCP server that enables LLMs to perform semantic and fulltext searches within Neo4j while executing complex, search-augmented Cypher queries for GraphRAG applications. It provides tools for database schema discovery and supports multi-provider embeddings to facilitate advanced graph traversals.53MIT