Neo4j MCP - Model Context Protocol for Neo4j

A robust Model Context Protocol (MCP) implementation that enables LLMs to interact with Neo4j graph databases using natural language.

This server uses a stable, synchronous Neo4j driver wrapped for asynchronous use, ensuring reliable connections and compatibility with modern MCP clients.

🚀 Features

Full Read/Write Access: Execute both read and write Cypher queries.
Flexible Authentication: Connect to Neo4j with or without authentication.
Schema Introspection: Automatically discover database schema (labels, relationship types).
Secure Configuration: Environment-based configuration using a .env file.
LLM Integration: Ready to use with Cursor, Claude Desktop, and other MCP-compatible tools.
Robust Error Handling: Clear error messages for connection and query issues.
Parameterized Queries: Support for safe, parameterized queries to prevent injection.

📋 Prerequisites

Python 3.8+
A running Neo4j database (local, Docker, or cloud).
pip for installing packages.

🔧 Installation

Clone the repository:

git clone https://github.com/your-repo/neo4j-mcp.git
cd neo4j-mcp

Install in editable mode: This is the recommended way to install, as it links the neo4j-mcp-server command directly to your source code.
```
pip install -e .
```

⚙️ Configuration

Configuration is managed via a .env file in the project root.

Create a .env file.
Add your Neo4j connection details.

Example 1: Local Neo4j without Authentication

Create a .env file with the following content. Leave NEO4J_USERNAME and NEO4J_PASSWORD blank.

# .env file
NEO4J_HOST=localhost
NEO4J_PORT=7687
NEO4J_USERNAME=
NEO4J_PASSWORD=
NEO4J_DATABASE=neo4j

Example 2: Local or Cloud Neo4j with Authentication

# .env file
NEO4J_HOST=localhost
NEO4J_PORT=7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-secret-password
NEO4J_DATABASE=neo4j

Example 3: Encrypted Connection (Aura)

For cloud services like Neo4j Aura, use the neo4j+s scheme and set NEO4J_ENCRYPTED to true.

# .env file
NEO4J_HOST=xxx.databases.neo4j.io
NEO4J_PORT=7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-aura-password
NEO4J_DATABASE=neo4j
NEO4J_URI_SCHEME=neo4j+s
NEO4J_ENCRYPTED=true

🏃 Quick Start

With your .env file configured and dependencies installed, you can start the server.

# Start the MCP server
neo4j-mcp-server

The server will start and listen for connections over stdio. If you see INFO:neo4j_mcp.server:Starting Neo4j MCP Server (stdio), it's working!

You can also start it with an SSE transport for web-based clients:

neo4j-mcp-server --transport sse --port 3000

🔌 LLM Integration (Cursor Example)

Make sure the server is installed and your .env file is configured.
In Cursor, open the MCP configuration file (~/.cursor/mcp.json or via the @ symbol > Tools > Settings icon).
Add the following server configuration. The server uses the .env file from its own directory, so you don't need to specify credentials here.

{
  "mcp.servers": {
    "neo4j": {
      "command": "neo4j-mcp-server",
      "transport": "stdio"
    }
  }
}

Restart Cursor. The @neo4j tool should now be available and connected.

🛠️ Available Tools

read_cypher_query(query, [parameters], [database]): Execute a read-only query.
write_cypher_query(query, [parameters], [database]): Execute a write query.
get_database_schema([database]): Get database labels and relationship types.
test_database_connection(): Verify the connection and get server info.
run_cypher_query(query, [parameters], [database], [read_only]): Run a query with explicit read/write mode.

🚨 Troubleshooting

AttributeError: type object 'SessionConfig' has no attribute 'AccessMode': Your neo4j library version might be incompatible. The project is tested with neo4j>=5.15.0.
ConnectionError: Neo4j authentication failed: Check your NEO4J_USERNAME and NEO4J_PASSWORD in the .env file. If your database has no auth, ensure these are blank.
ConnectionError: Neo4j service unavailable: Make sure your Neo4j database is running and accessible at the specified NEO4J_HOST and NEO4J_PORT.

Made with ❤️ for the Neo4j and MCP communities