What is Neo4j Mcp

neo4j-mcp is a Cursor MCP (Model Context Protocol) server that facilitates seamless interaction with Neo4j databases directly from the Cursor IDE, allowing developers to manage and query their databases efficiently.

Use cases

Use cases for neo4j-mcp include developing applications that require complex data relationships, real-time data analysis, and interactive data visualization, as well as educational purposes for learning about graph databases.

How to use

To use neo4j-mcp, clone the repository, install dependencies using Bun, configure your Neo4j credentials in a .env file, and run the server. You can also use Docker Compose to easily set up and run Neo4j in a container.

Key features

Key features include the ability to connect to Neo4j databases, execute Cypher queries, transform Neo4j-specific data types to standard JavaScript objects, secure credential management via environment variables, and detailed database metrics and diagnostics.

Where to use

neo4j-mcp can be used in various fields such as data analysis, application development, and any scenario where graph databases are utilized, particularly in projects that require integration with the Cursor IDE.

Neo4j MCP Server for Cursor

A Cursor MCP (Model Context Protocol) server that enables seamless interaction with Neo4j databases directly from the Cursor IDE.

Features

• Connect to Neo4j databases
• Execute Cypher queries and retrieve results
• Transform Neo4j-specific data types to standard JavaScript objects
• Uses the official MCP SDK with stdio transport for seamless integration with Cursor
• Support for environment variables for secure credential management
• Retrieve detailed database information and metrics
• Monitor connection status and diagnostics

Prerequisites

• Bun (v1.0.0 or higher)
• Neo4j database (local or remote)

Running Neo4j with Docker Compose

This project includes a Docker Compose configuration to easily run Neo4j in a container:

1. Make sure you have Docker and Docker Compose installed.

2. Start Neo4j using Docker Compose:

   docker-compose up -d
   

3. Access the Neo4j Browser at http://localhost:7474

   • Default username: neo4j
   • Default password: your_password (as specified in the docker-compose.yml)

4. To stop Neo4j:

   docker-compose down
   

5. To stop Neo4j and remove all data:

   docker-compose down -v
   

Note: The default password in docker-compose.yml is set to your_password. For production use, change this to a secure password and update your .env file accordingly.

Installation

1. Clone this repository:

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

2. Install dependencies:

   bun install
   

3. Configure environment variables:
   Create a .env file in the root directory with your Neo4j credentials:

   NEO4J_URI=neo4j://localhost:7687
   NEO4J_USERNAME=neo4j
   NEO4J_PASSWORD=your_password
   NEO4J_DATABASE=neo4j
   NODE_ENV=development
   

Usage

Starting the Server

The server uses stdio transport for communication with Cursor, so it should be started by Cursor itself. However, you can test it manually:

# Run directly
bun run index.ts

# Run with logging using the provided script
./run-mcp-server.sh

Available Tools

The MCP server exposes the following tools:

1. Connect to Neo4j with Explicit Credentials

Connects to a Neo4j database with the provided credentials.

Parameters:

• uri: Neo4j database URI (e.g., neo4j://localhost:7687)
• username: Neo4j database username
• password: Neo4j database password
• database: (Optional) Neo4j database name

2. Connect to Neo4j with Environment Variables

Connects to a Neo4j database using credentials from environment variables.

No parameters required.

3. Execute a Cypher Query

Executes a Cypher query against the connected Neo4j database.

Parameters:

• query: Cypher query to execute
• params: (Optional) Query parameters

4. Get Database Information

Retrieves detailed information about the connected Neo4j database, including:

• Neo4j version and edition
• Database name
• Node and relationship counts
• Available labels
• Relationship types

No parameters required.

5. Get Connection Status

Retrieves the current connection status, including:

• Connection state (connected/disconnected)
• Connection details (URI, database)
• Connection time
• Last error (if any)

No parameters required.

6. Disconnect from Neo4j

Disconnects from the Neo4j database.

No parameters required.

Environment Variables

The following environment variables can be set in a .env file:

Integration with Cursor

This MCP server is designed to be used with Cursor’s MCP integration. Cursor will automatically detect and use the tools provided by this server.

Development

Project Structure

• index.ts - Entry point that starts the MCP server
• src/mcpNeo4jServer.ts - MCP server implementation using the MCP SDK
• src/services/neo4jService.ts - Neo4j service for database operations
• src/types/index.ts - TypeScript type definitions
• src/utils/errorHandler.ts - Utility functions for error handling

Building for Production

To build the server for production:

# Build the server
bun build index.ts --outdir ./dist

# Make the output file executable
chmod +x ./dist/index.js

The build process bundles all dependencies into a single JavaScript file, making it easy to distribute and run the server without installing dependencies.

Running the Server

You can run the server using the provided shell script:

./run-mcp-server.sh

This script:

• Sets the working directory to the script’s location
• Creates a logs directory if it doesn’t exist
• Runs the server using Bun and logs output to logs/mcp-server.log

Note: The script requires Bun to be installed and available in your PATH.

License

MIT