Neo4j MCP Server for Cursor: MCP-Driven Workflows & Seamless Access

Key Features of Neo4j MCP Server for Cursor: MCP-Driven Workflows & Seamless Access?

Distinctive capabilities include:

• Type-Centric Data Handling: Converts Neo4j’s proprietary data structures into JavaScript objects seamlessly, simplifying frontend integration.
• Security-First Design: Environment variables decouple credentials from code, reducing exposure of sensitive information.
• Diagnostic Depth: Real-time metrics on node/relationship counts, connection uptime, and error logs enhance troubleshooting efficiency.
• Protocol Adherence: Full compliance with Cursor’s MCP standards ensures frictionless tool discovery and execution.

These features collectively minimize boilerplate code, empowering developers to focus on logic rather than infrastructure.

Use Cases of Neo4j MCP Server for Cursor: MCP-Driven Workflows & Seamless Access?

Typical applications span:

• Rapid Prototyping: Developers can test Cypher queries interactively without leaving the IDE, accelerating graph schema iteration.
• CI/CD Pipelines: Automated database health checks via Get Connection Status can be embedded in deployment workflows.
• Multi-Environment Management: Toggle between development and production databases effortlessly using environment variables.
• Collaborative Debugging: Shareable database snapshots and connection diagnostics facilitate remote team troubleshooting.

Its adaptability makes it indispensable for teams relying on Neo4j for complex relationship modeling.

FAQ from Neo4j MCP Server for Cursor: MCP-Driven Workflows & Seamless Access?

How do I secure credentials beyond environment variables?

Implement secrets management tools like Vault, injecting values dynamically into the .env during runtime.

What if the Docker container fails to start?

Verify port conflicts (7474/7687) and ensure Neo4j’s dbms.default_listen_address=0.0.0.0 is set in neo4j.conf.

Can I extend this server with custom tools?

Absolutely—modify the mcpNeo4jServer.ts interface to add domain-specific operations while adhering to MCP conventions.

Why use Bun over Node.js?

Bun’s faster dependency resolution and single-threaded execution make it ideal for lightweight, high-performance server-side workflows.

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