Neo4j MCP server

This server implements the Model Context Protocol (MCP) to connect large language models like Claude Desktop with Neo4j databases, allowing natural language interactions with graph databases. Use it to perform Cypher queries, store knowledge graph memory, or manage graph-based memory through simple conversational commands.

Available Servers

MCP Neo4j Cypher Server

The mcp-neo4j-cypher server converts natural language into Cypher queries that can be executed against your Neo4j database. This allows you to query your graph database using plain English commands like "What is in this graph?"

MCP Neo4j Memory Server

The mcp-neo4j-memory server provides knowledge graph memory capabilities using Neo4j as the storage backend. It helps maintain context between interactions by storing information in a structured graph format.

MCP JSON Memory Server

The mcp-json-memory server offers knowledge graph memory storage using a simple JSON file instead of Neo4j. This is a reference implementation that demonstrates memory modeling as a knowledge graph.

Installation

Prerequisites

• Node.js and npm
• Access to a Neo4j database (local or Aura)

Installing from npm

npm install mcp-neo4j-server

Manual Installation

1. Clone the repository:

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

2. Install dependencies:

npm install

Configuration

Create a configuration file (config.json) with your Neo4j credentials:

{
  "neo4j": {
    "uri": "neo4j+s://your-instance-id.databases.neo4j.io",
    "username": "neo4j",
    "password": "your-password"
  },
  "memory": {
    "type": "neo4j",  // or "json" for file-based storage
    "filePath": "./memory.json"  // only needed for JSON memory type
  }
}

Usage

Starting the Server

npx mcp-neo4j-server --config ./config.json

Or if installed manually:

node server.js --config ./config.json

By default, the server runs on port 8080. You can specify a different port:

npx mcp-neo4j-server --port 3000 --config ./config.json

Connecting with an MCP Client

1. Open your MCP client (e.g., Claude Desktop)
2. Add a new tool/service with the server address: http://localhost:8080
3. Start interacting with your Neo4j database using natural language

Example Queries

Here are some examples of natural language queries you can use:

• "What is in this graph?"
• "Show me all Person nodes"
• "Create a new Movie node titled 'The Matrix'"
• "Find connections between Person and Movie nodes"
• "Remember that I prefer sci-fi movies"
• "What do you know about my preferences?"

API Endpoints

The server exposes standard MCP endpoints:

• /mcp/describe: Returns information about the server capabilities
• /mcp/execute: Processes natural language commands and returns results
• /mcp/health: Health check endpoint

Troubleshooting

If you encounter connection issues:

• Verify your Neo4j credentials in the config file
• Ensure your Neo4j instance is running and accessible
• Check firewall settings if connecting to a remote database
• Examine server logs for detailed error messages

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.