📌Overview

Purpose: To enable seamless integration between the Neo4j graph database and Claude Desktop, facilitating natural language interactions for graph database operations.

Overview: The MCP Neo4j Server offers a robust solution for users to interact with Neo4j databases through natural language queries and commands. This framework simplifies database management tasks while ensuring security and structured data handling.

Key Features:

Execute Query: Allows users to run Cypher queries on the Neo4j database, supporting all query types (READ, CREATE, UPDATE, DELETE) while returning results in a structured format and providing protection against injection attacks.
Create Node: Enables the creation of new nodes in the graph database with customizable labels and properties, supporting various Neo4j data types and returning the internal ID of the created node.
Create Relationship: Facilitates the establishment of relationships between existing nodes, allowing the definition of relationship types, directions, and properties while requiring the node IDs for the connection.

MCP Neo4j Server

An MCP server that provides integration between Neo4j graph database and Claude Desktop, enabling graph database operations through natural language interactions.

Quick Start

You can run this MCP server directly using npx:

npx @alanse/mcp-neo4j

Or add it to your Claude Desktop configuration:

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

Features

This server provides tools for interacting with a Neo4j database:

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
- Parameters can be passed 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

Installation

Installing via Smithery

To install MCP Neo4j Server for Claude Desktop automatically via Smithery:

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

For Development

Clone the repository:

git clone https://github.com/da-okazaki/mcp-neo4j-server.git
cd mcp-neo4j-server

Install dependencies:

npm install

Build the project:

npm run build

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)

Usage Examples

Interact with the Neo4j database using natural language:

Querying Data

Examples of queries:

"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 of instructions:

"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 of requests:

"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 of complex operations:

"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]

Testing

Run the test suite:

npm test

License

MIT