Installation

Quickstart with Homebrew (Mac only):

brew install neo4j-mcp

Manually install the server

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

Download the archive for your operating system.
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"
      }
    }
  }
}

HTTP Mode Configuration (VSCode)

For HTTP mode, you can configure with Basic Authentication or Bearer Token authentication.

Option 1: Basic Authentication

{
  "servers": {
    "neo4j-http": {
      "type": "http",
      "url": "http://127.0.0.1:80/mcp",
      "headers": {
        "Authorization": "Basic BASE64_ENCODED_CREDENTIALS"
      }
    }
  }
}

Generate the base64-encoded credentials:

echo -n "neo4j:password" | base64

Option 2: Bearer Token (Enterprise/Aura with SSO)

For Neo4j Enterprise or Aura with SSO/OAuth configured:

{
  "servers": {
    "neo4j-http-bearer": {
      "type": "http",
      "url": "http://127.0.0.1:80/mcp",
      "headers": {
        "Authorization": "Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
      }
    }
  }
}

Replace the bearer token with your actual OAuth/SSO token from your identity provider.

For HTTP mode configuration, TLS/HTTPS setup, and detailed transport mode documentation, see Transport modes, Configuration, and TLS/HTTPS Setup sections.

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 for STDIO mode and have no default values.

HTTP Mode Configuration (Claude Desktop)