mcp-neo4j-cypher 0.5.2
A simple Neo4j MCP server
Requires Python: >=3.10

# 🔍⁉️ 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.

![text2cypher-workflow](./assets/images/text2cypher-process.png)


## 🧩 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
  - 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:**
```bash
mcp-neo4j-cypher --read-timeout 60  # 60 seconds
```

**Environment Variable:**
```bash
export NEO4J_READ_TIMEOUT=60
```

**Docker:**
```bash
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:**
```bash
mcp-neo4j-cypher --token-limit 4000
```

**Environment Variable:**
```bash
export NEO4J_RESPONSE_TOKEN_LIMIT=4000
```

**Docker:**
```bash
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:**
```bash
mcp-neo4j-cypher --sample 1000  # Sample 1000 nodes per label
```

**Environment Variable:**
```bash
export NEO4J_SCHEMA_SAMPLE_SIZE=1000
```

**Docker:**
```bash
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](https://neo4j.com/docs/apoc/current/overview/apoc.meta/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:**

```bash
# 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:

```bash
# 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 `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:**
```bash
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:**
```bash
export NEO4J_MCP_SERVER_ALLOW_ORIGINS="https://example.com,https://example.com"
```

### 🔧 Complete Security Configuration

**Development Setup:**
```bash
mcp-neo4j-cypher --transport http \
  --allowed-hosts "localhost,127.0.0.1" \
  --allow-origins "http://localhost:3000"
```

**Production Setup:**
```bash
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 credentials
- Use 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](https://github.com/neo4j-contrib/mcp-neo4j/releases) 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.

```json
{
  "mcpServers": {
    "neo4j-database": {
      "command": "uvx",
      "args": [ "mcp-neo4j-cypher@0.5.2", "--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:

```bash
# 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-cypher
```

### Multiple Database Example

Here's an example of connecting to multiple Neo4j databases using namespaces:

```json
{
  "mcpServers": {
    "movies-neo4j": {
      "command": "uvx",
      "args": ["mcp-neo4j-cypher@0.5.2", "--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.5.2"],
      "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:

<details>
  <summary>Legacy Syntax</summary>

```json
"mcpServers": {
  "neo4j": {
    "command": "uvx",
    "args": [
      "mcp-neo4j-cypher@0.5.2",
      "--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/"
    ]
  }
}
```

</details>

### 🐳 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 8000 
* `NEO4J_TRANSPORT=stdio`: Uses stdio transport for Claude Desktop compatibility
* `NEO4J_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

```json
{
  "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 .`:

```bash
# 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_URI`                        | `bolt://localhost:7687`                 | Neo4j connection URI                               |
| `NEO4J_USERNAME`                   | `neo4j`                                 | Neo4j username                                     |
| `NEO4J_PASSWORD`                   | `password`                              | Neo4j password                                     |
| `NEO4J_DATABASE`                   | `neo4j`                                 | Neo4j database name                                |
| `NEO4J_TRANSPORT`                  | `stdio` (local), `http` (remote)        | Transport protocol (`stdio`, `http`, or `sse`)     |
| `NEO4J_NAMESPACE`                  | _(empty)_                               | Tool namespace prefix                              |
| `NEO4J_MCP_SERVER_HOST`            | `127.0.0.1` (local)                     | Host to bind to                                    |
| `NEO4J_MCP_SERVER_PORT`            | `8000`                                  | Port for HTTP/SSE transport                        |
| `NEO4J_MCP_SERVER_PATH`            | `/api/mcp/`                             | Path for accessing MCP server                      |
| `NEO4J_MCP_SERVER_ALLOW_ORIGINS`   | _(empty - secure by default)_           | Comma-separated list of allowed CORS origins       |
| `NEO4J_MCP_SERVER_ALLOWED_HOSTS`   | `localhost,127.0.0.1`                   | Comma-separated list of allowed hosts (DNS rebinding protection) |
| `NEO4J_RESPONSE_TOKEN_LIMIT`       | _(none)_                                | Maximum tokens for read query responses            |
| `NEO4J_READ_TIMEOUT`               | `30`                                    | Timeout in seconds for read queries                |
| `NEO4J_READ_ONLY`                  | `false`                                 | Allow only read-only queries (true/false)          |
| `NEO4J_SCHEMA_SAMPLE_SIZE`                     | `1000`                                  | Number of nodes to sample for schema inspection (set to -1 for full scan) |

### 🌐 SSE Transport for Legacy Web Access

When using SSE transport (for legacy web clients), the server exposes an HTTP endpoint:

```bash
# 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:

```yaml
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:

```json
{
  "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

1. Install [`uv`](https://github.com/astral-sh/uv):

```bash
# Using pip
pip install uv

# Using Homebrew on macOS
brew install uv

# Using cargo (Rust package manager)
cargo install uv
```

2. Clone the repository and set up development environment:

```bash
# 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]"
```

3. Run Integration Tests

```bash
./tests.sh
```

### 🔧 Development Configuration

For development with Claude Desktop using the local source:

```json
{
  "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.