Neo4j MCP server

Integrates with Neo4j graph databases to enable natural language querying, node creation, and complex graph operations for knowledge exploration and data relationship modeling.
Back to servers
Setup instructions
Provider
Daichi Okazaki
Release date
Jan 06, 2025
Language
TypeScript
Package
Stats
1.8K downloads
51 stars

The MCP Neo4j Server provides integration between Neo4j graph database and Claude Desktop, enabling you to perform graph database operations through natural language interactions. It allows Claude to execute queries, create nodes and relationships, and more, all through conversational prompts.

Installation Options

Quick Start with npx

Run the MCP server directly using npx:

npx @alanse/mcp-neo4j

Add to Claude Desktop Configuration

Edit your Claude Desktop configuration file to include the Neo4j server:

{
  "mcpServers": {
    "neo4j": {
      "command": "npx",
      "args": ["@alanse/mcp-neo4j-server"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your-password",
        "NEO4J_DATABASE": "neo4j"
      }
    }
  }
}

Automated Installation via Smithery

Install the MCP Neo4j Server for Claude Desktop using Smithery:

npx -y @smithery/cli install @alanse/mcp-neo4j-server --client claude

Configuration

The server requires the following environment variables:

  • NEO4J_URI: Neo4j database URI (default: bolt://localhost:7687)
  • NEO4J_USERNAME: Neo4j username (default: neo4j)
  • NEO4J_PASSWORD: Neo4j password (required)
  • NEO4J_DATABASE: Neo4j database name (default: neo4j)

Neo4j Enterprise Support

For Neo4j Enterprise users with multiple databases, you can specify which database to connect to:

{
  "env": {
    "NEO4J_URI": "bolt://localhost:7687",
    "NEO4J_USERNAME": "neo4j",
    "NEO4J_PASSWORD": "your-password",
    "NEO4J_DATABASE": "myCustomDatabase"
  }
}

This will connect to "myCustomDatabase" instead of the default "neo4j" database.

Features and Usage

Available Tools

  • execute_query: Execute Cypher queries on the Neo4j database

    • Supports all types of Cypher queries (READ, CREATE, UPDATE, DELETE)
    • Returns query results in a structured format
    • Accepts parameters to prevent injection attacks
  • create_node: Create a new node in the graph database

    • Specify node labels and properties
    • Returns the created node with its internal ID
    • Supports all Neo4j data types for properties
  • create_relationship: Create a relationship between two existing nodes

    • Define relationship type and direction
    • Add properties to relationships
    • Requires node IDs for source and target nodes

Querying Data Examples

You can ask Claude questions like:

  • "Show me all employees in the Sales department"
  • "Find the top 5 oldest customers"
  • "Who has purchased more than 3 products in the last month?"

Example interaction:

User: "Show me all employees in the Sales department"

Claude: Let me query the database for Sales department employees.

[Executes query internally: MATCH (e:Employee)-[:WORKS_IN]->(d:Department {name: 'Sales'}) RETURN e.name, e.position]

Result:
- John Smith (Sales Manager)
- Sarah Johnson (Sales Representative)
- Mike Brown (Account Executive)

Creating Data Examples

You can give instructions like:

  • "Add a new person named John Doe who is 30 years old"
  • "Create a product called 'Premium Coffee' with price $24.99"
  • "Add a new department called 'Research & Development'"

Example interaction:

User: "Add a new person named John Doe who is 30 years old"

Claude: I'll create a new Person node with the provided information.

[Creates node internally with label 'Person' and properties {name: 'John Doe', age: 30}]

Result: Created new person node with ID: 123

Creating Relationships Examples

You can request relationships like:

  • "Make John Doe friends with Jane Smith"
  • "Set Product A as a component of Product B"
  • "Assign John Doe to the Sales department"

Example interaction:

User: "Make John Doe friends with Jane Smith"

Claude: I'll create a friendship relationship between these two people.

[Creates relationship internally: MATCH (a:Person {name: 'John Doe'}), (b:Person {name: 'Jane Smith'})
CREATE (a)-[:FRIENDS_WITH {since: '2024-01-05'}]->(b)]

Result: Created friendship relationship between John Doe and Jane Smith

Complex Operations Examples

You can perform more complex operations with natural language:

  • "Find all products purchased by customers who live in New York"
  • "Show me friends of friends of John Doe"
  • "Calculate the average age of employees in each department"

Example interaction:

User: "Find all products purchased by customers who live in New York"

Claude: I'll query the database for this information.

[Executes query internally:
MATCH (c:Customer {city: 'New York'})-[:PURCHASED]->(p:Product)
RETURN c.name, collect(p.name) as products]

Result:
- Alice Wilson: [Premium Coffee, Tea Set, Cookies]
- Bob Miller: [Premium Coffee, Water Bottle]

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "neo4j" '{"command":"npx","args":["@alanse/mcp-neo4j-server"],"env":{"NEO4J_URI":"bolt://localhost:7687","NEO4J_USERNAME":"neo4j","NEO4J_PASSWORD":"your-password"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "neo4j": {
            "command": "npx",
            "args": [
                "@alanse/mcp-neo4j-server"
            ],
            "env": {
                "NEO4J_URI": "bolt://localhost:7687",
                "NEO4J_USERNAME": "neo4j",
                "NEO4J_PASSWORD": "your-password"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "neo4j": {
            "command": "npx",
            "args": [
                "@alanse/mcp-neo4j-server"
            ],
            "env": {
                "NEO4J_URI": "bolt://localhost:7687",
                "NEO4J_USERNAME": "neo4j",
                "NEO4J_PASSWORD": "your-password"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect

Want to 10x your AI skills?

Get a free account and learn to code + market your apps using AI (with or without vibes!).

Nah, maybe later