mcp-neo4j-cypher 0.2.0

A simple Neo4j MCP server

🔍⁉️ 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 with Claude's analysis.

🧩 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

• 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, ... }

🕸️ 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
  • No input required
  • Returns: JSON serialized list of node labels with two dictionaries: one for attributes and one for relationships

🔧 Usage with Claude Desktop

💾 Released Package

Can be found on PyPi https://pypi.org/project/mcp-neo4j-cypher/

Add the server to your claude_desktop_config.json with configuration through environment variables:

"mcpServers": {
  "neo4j-aura": {
    "command": "uvx",
    "args": [ "mcp-neo4j-cypher==0.2.0" ],
    "env": {
      "NEO4J_URI": "bolt://localhost:7687",
      "NEO4J_USERNAME": "neo4j",
      "NEO4J_PASSWORD": "<your-password>",
      "NEO4J_DATABASE": "neo4j"
    }
  }
}

Here is an example connection for the movie database with Movie, Person (Actor, Director), Genre, User and ratings:

{
  "mcpServers": {
    "movies-neo4j": {
      "command": "uvx",
      "args": ["mcp-neo4j-cypher==0.2.0"],
      "env": {
        "NEO4J_URI": "neo4j+s://demo.neo4jlabs.com",
        "NEO4J_USERNAME": "recommendations",
        "NEO4J_PASSWORD": "recommendations"
      }
    }   
  }
}

Syntax with --db-url, --username and --password command line arguments is still supported but environment variables are preferred:

Legacy Syntax

"mcpServers": {
  "neo4j": {
    "command": "uvx",
    "args": [
      "mcp-neo4j-cypher==0.1.1",
      "--db-url",
      "bolt://localhost",
      "--username",
      "neo4j",
      "--password",
      "<your-password>"
    ]
  }
}

Here is an example connection for the movie database with Movie, Person (Actor, Director), Genre, User and ratings:

{
  "mcpServers": {
    "movies-neo4j": {
      "command": "uvx",
      "args": ["mcp-neo4j-cypher==0.1.2", 
      "--db-url", "neo4j+s://demo.neo4jlabs.com", 
      "--user", "recommendations", 
      "--password", "recommendations"]
    }   
  }
}

🐳 Using with Docker

"mcpServers": {
  "neo4j": {
    "command": "docker",
    "args": [
      "run",
      "--rm",
      "-e", "NEO4J_URI=bolt://host.docker.internal:7687",
      "-e", "NEO4J_USERNAME=neo4j",
      "-e", "NEO4J_PASSWORD=<your-password>",
      "mcp/neo4j-cypher:0.2.0"
    ]
  }
}

🚀 Development

📦 Prerequisites

1. Install uv (Universal Virtualenv):

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

# Clone the repository
git clone https://github.com/yourusername/mcp-neo4j-cypher.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

CLOSE ANY LOCAL NEO4J DATABASES BEFORE RUNNING TESTS

• Tests will deploy a local docker container containing the test Neo4j instance.
• However if a Neo4j database is running locally, then the test driver may connect here instead.
• This will result in you local Neo4j database having its contents erased.

./tests.sh

🔧 Development Configuration

# Add the server to your claude_desktop_config.json
"mcpServers": {
  "neo4j": {
    "command": "uv",
    "args": [
      "--directory", "parent_of_servers_repo/servers/mcp-neo4j-cypher/src",
      "run", "mcp-neo4j-cypher"],
    "env": {
      "NEO4J_URI": "bolt://localhost",
      "NEO4J_USERNAME": "neo4j",
      "NEO4J_PASSWORD": "<your-password>"
    }
  }
}

🐳 Docker

Build and run the Docker container:

# Build the image
docker build -t mcp/neo4j-cypher:latest .

# Run the container
docker run -e NEO4J_URI="bolt://host.docker.internal:7687" \
          -e NEO4J_USERNAME="neo4j" \
          -e NEO4J_PASSWORD="your-password" \
          mcp/neo4j-cypher:latest

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