Installation

The Model Context Protocol (MCP) server for Neo4j is in active development and not yet suitable for production.

Visit the release page for Neo4j MCP: https://github.com/neo4j/mcp/releases

  1. Download the archive for your operating system.

  2. Extract and place neo4j-mcp in a directory present in your PATH variables.

Mac and Linux:

chmod +x neo4j-mcp
sudo mv neo4j-mcp /usr/local/bin/

Windows (PowerShell or cmd):

move neo4j-mcp.exe C:\Windows\System32

Verify the neo4j-mcp installation:

neo4j-mcp -v

This should print the installed version.

Configure VSCode (MCP)

Create / edit mcp.json:

{
  "servers": {
    "neo4j": {
      "type": "stdio",
      "command": "neo4j-mcp",
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "password",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_READ_ONLY": "true"
      }
    }
  }
}

Set environment variables in the env object as shown above.

Alternatively, you can use command-line flags in the args array to override environment variables:

{
  "servers": {
    "neo4j": {
      "type": "stdio",
      "command": "neo4j-mcp",
      "args": [
        "--neo4j-uri", "bolt://localhost:7687",
        "--neo4j-username", "neo4j",
        "--neo4j-password", "password",
        "--neo4j-database", "neo4j"
      ],
      "env": {
        "NEO4J_READ_ONLY": "true"
      }
    }
  }
}

Restart VSCode. Open Copilot Chat and make sure that the prompt "List Neo4j MCP tools" returns expected results.

Also refer to VSCode Copilot docs.

Configure Claude desktop

Install Claude for desktop.

Configure Claude for desktop for all MCP servers you want to use. Open your Claude for desktop App configuration in a text editor. Find the files at:

  • (MacOS/Linux) ~/Library/Application Support/Claude/claude_desktop_config.json

  • (Windows) $env:AppData\Claude\claude_desktop_config.json

Make sure to create the file if it doesn’t exist.

Add the neo4j-mcp MCP in the mcpServers key:

{
  "mcpServers": {
    "neo4j-mcp": {
      "type": "stdio",
      "command": "neo4j-mcp",
      "args": [],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "password",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_READ_ONLY": "true"
      }
    }
  }
}

Set environment variables in the env object as shown above.

Alternatively, you can use command-line flags in the args array:

{
  "mcpServers": {
    "neo4j-mcp": {
      "type": "stdio",
      "command": "neo4j-mcp",
      "args": [
        "--neo4j-uri", "bolt://localhost:7687",
        "--neo4j-username", "neo4j",
        "--neo4j-password", "password",
        "--neo4j-database", "neo4j"
      ],
      "env": {
        "NEO4J_READ_ONLY": "true"
      }
    }
  }
}

Notes:

  • Command-line flags (in args) take precedence over environment variables (in env).

  • NEO4J_READ_ONLY is optional. Set to true to disable write tools.

  • Neo4j Desktop example URI: bolt://localhost:7687.

  • For Aura, use the connection string from the Aura Console.

  • All connection parameters (URI, username, password) are required and have no default values.