Client configuration

VSCode configuration

Create / edit mcp.json:

{
  "servers": {
    "neo4j": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "neo4j_mcp_server"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "password",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_READ_ONLY": "true",
        "NEO4J_TELEMETRY": "false",
        "NEO4J_LOG_LEVEL": "info",
        "NEO4J_LOG_FORMAT": "text",
        "NEO4J_SCHEMA_SAMPLE_SIZE": "100"
      }
    }
  }
}

{
  "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",
        "NEO4J_TELEMETRY": "false",
        "NEO4J_LOG_LEVEL": "info",
        "NEO4J_LOG_FORMAT": "text",
        "NEO4J_SCHEMA_SAMPLE_SIZE": "100"
      }
    }
  }
}

Also see Add and manage MCP servers in VS Code.

The first three environment variables (NEO4J_URI, NEO4J_USERNAME and NEO4J_PASSWORD) are required. The server fails to start if any of these are missing.

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": "python",
      "args": [
        "-m", "neo4j_mcp_server",
        "--neo4j-uri", "bolt://localhost:7687",
        "--neo4j-username", "neo4j",
        "--neo4j-password", "password",
        "--neo4j-database", "neo4j",
        "--neo4j-telemetry": "false",
        "--neo4j-log-level": "info",
        "--neo4j-log-format": "text",
        "--neo4j-schema-sample-size": "100"
      ],
      "env": {
        "NEO4J_READ_ONLY": "true"
      }
    }
  }
}

{
  "servers": {
    "neo4j": {
      "type": "stdio",
      "command": "neo4j-mcp",
      "args": [
        "--neo4j-uri", "bolt://localhost:7687",
        "--neo4j-username", "neo4j",
        "--neo4j-password", "password",
        "--neo4j-database", "neo4j",
        "--neo4j-telemetry": "false",
        "--neo4j-log-level": "info",
        "--neo4j-log-format": "text",
        "--neo4j-schema-sample-size": "100"
      ],
      "env": {
        "NEO4J_READ_ONLY": "true"
      }
    }
  }
}

Restart VSCode; open Copilot Chat and prompt "List Neo4j MCP tools" to confirm.

Claude Desktop configuration

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 python command and the neo4j_mcp_server argument in the mcpServers key:

{
  "mcpServers": {
    "neo4j-mcp": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "neo4j_mcp_server"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "password",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_READ_ONLY": "true",
        "NEO4J_TELEMETRY": "false",
        "NEO4J_LOG_LEVEL": "info",
        "NEO4J_LOG_FORMAT": "text",
        "NEO4J_SCHEMA_SAMPLE_SIZE": "100"
      }
    }
  }
}

{
  "mcpServers": {
    "neo4j-mcp": {
      "type": "stdio",
      "command": "neo4j-mcp",
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "password",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_READ_ONLY": "true",
        "NEO4J_TELEMETRY": "false",
        "NEO4J_LOG_LEVEL": "info",
        "NEO4J_LOG_FORMAT": "text",
        "NEO4J_SCHEMA_SAMPLE_SIZE": "100"
      }
    }
  }
}

The first three environment variables (NEO4J_URI, NEO4J_USERNAME and NEO4J_PASSWORD) are required. The server fails to start if any of these are missing.

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": "python",
      "args": [
        "-m", "neo4j_mcp_server",
        "--neo4j-uri", "bolt://localhost:7687",
        "--neo4j-username", "neo4j",
        "--neo4j-password", "password",
        "--neo4j-database", "neo4j",
        "--neo4j-telemetry": "false",
        "--neo4j-log-level": "info",
        "--neo4j-log-format": "text",
        "--neo4j-schema-sample-size": "100"
      ],
      "env": {
        "NEO4J_READ_ONLY": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "neo4j-mcp": {
      "type": "stdio",
      "command": "neo4j-mcp",
      "args": [
        "--neo4j-uri", "bolt://localhost:7687",
        "--neo4j-username", "neo4j",
        "--neo4j-password", "password",
        "--neo4j-database", "neo4j",
        "--neo4j-telemetry": "false",
        "--neo4j-log-level": "info",
        "--neo4j-log-format": "text",
        "--neo4j-schema-sample-size": "100"
      ],
      "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.