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:

Variable	Description	Default
NEO4J_URI	Neo4j database URI	neo4j://localhost:7687
NEO4J_USERNAME	Neo4j database username	neo4j
NEO4J_PASSWORD	Neo4j database password	(empty)
NEO4J_DATABASE	Neo4j database name	(default database)
NODE_ENV	Environment (development/production)	development

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