Neo4j MCP Skill

Neo4j MCP Skill

Installs and configures the official Neo4j MCP server so AI agents can connect to Neo4j via any MCP-compatible client.

When to Use

• Connecting Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Kiro, or another editor to Neo4j via MCP
• Installing neo4j-mcp-server and writing the correct config for a specific editor
• Switching between stdio and HTTP transport
• Enabling or disabling write access (NEO4J_READ_ONLY)
• Troubleshooting "MCP server not found" or connection errors

When NOT to Use

• Writing or optimizing Cypher queries → use neo4j-cypher-skill
• Provisioning a new Neo4j Aura instance → use neo4j-aura-provisioning-skill
• Agent long-term memory → use neo4j-agent-memory-skill
• neo4j-admin / cypher-shell / aura-cli → use neo4j-cli-tools-skill

Available MCP Tools

| Tool | Type | What it does |

|---|---|---|

| get-schema | read | Returns labels, relationship types, property keys, and indexes |

| read-cypher | read | Executes read-only Cypher (MATCH, RETURN, SHOW) |

| write-cypher | write | Executes write Cypher (MERGE, CREATE, SET, DELETE) — disabled when NEO4J_READ_ONLY=true |

| list-gds-procedures | read | Lists available Graph Data Science procedures (requires GDS plugin) |

Installation

Step 1 — Install and find the absolute path

# Option A: pip (recommended)
pip install neo4j-mcp-server

# Option B: Download binary
# https://github.com/neo4j/mcp/releases -- macOS, Linux, Windows binaries

# Option C: Docker
docker pull neo4j/mcp

Get the absolute path — you will need this in Step 3:

which neo4j-mcp          # e.g. /usr/local/bin/neo4j-mcp
                         # or:  /Users/you/project/.venv/bin/neo4j-mcp  (if installed in venv)

neo4j-mcp --version      # confirm it runs

> Why absolute path matters: editors (Claude Code, Cursor, Claude Desktop) spawn the MCP server as a subprocess using their own restricted PATH — not your shell's PATH. On macOS, GUI apps do not inherit .zshrc or .zprofile. Using neo4j-mcp as the command will silently fail; using /full/path/to/neo4j-mcp always works. Always use the output of which neo4j-mcp in the command field below.

Step 2 — Prepare credentials

# .env (gitignored)
NEO4J_URI=neo4j+s://<instance>.databases.neo4j.io   # Aura
# or bolt://localhost:7687                           # local
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=<password>
NEO4J_DATABASE=neo4j

Verify connectivity before configuring the editor:

source .env
cypher-shell -a "$NEO4J_URI" -u "$NEO4J_USERNAME" -p "$NEO4J_PASSWORD" \
  "RETURN 'connected' AS status"
# If cypher-shell not available: python3 -c "
# from neo4j import GraphDatabase, __version__
# d = GraphDatabase.driver('$NEO4J_URI', auth=('$NEO4J_USERNAME','$NEO4J_PASSWORD'))
# d.verify_connectivity(); print('connected'); d.close()"

Step 3 — Configure your editor

Pick the config block for your editor. All use STDIO transport (the MCP server runs as a subprocess of the editor).

Claude Code — add to ~/.claude/settings.json. If the file already exists, merge the neo4j block into the existing mcpServers object — do not replace the whole file.

{
  "mcpServers": {
    "neo4j": {
      "command": "/full/path/to/neo4j-mcp",
      "env": {
        "NEO4J_URI": "neo4j+s://<host>",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "<password>",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_READ_ONLY": "true"
      }
    }
  }
}

CLI alternative (sets command only — you still need to add env vars to the file):

claude mcp add neo4j /full/path/to/neo4j-mcp

Claude Desktop

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "neo4j": {
      "command": "/full/path/to/neo4j-mcp",
      "env": {
        "NEO4J_URI": "neo4j+s://<host>",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "<password>",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_READ_ONLY": "true"
      }
    }
  }
}

VS Code — .vscode/mcp.json (note: uses servers, not mcpServers — different from all other editors):

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

Cursor — global: ~/.cursor/mcp.json / project: .cursor/mcp.json (same structure as Claude Code, uses mcpServers).

Windsurf — global: ~/.codeium/windsurf/mcp_config.json / project: .windsurf/mcp_config.json (same structure as Claude Code, uses mcpServers).

Kiro — global: ~/.kiro/settings/mcp.json / project: .kiro/settings/mcp.json. Supports ${VARIABLE} to pull from the shell environment exported before the editor launched:

{
  "mcpServers": {
    "neo4j": {
      "command": "/full/path/to/neo4j-mcp",
      "env": {
        "NEO4J_URI": "${NEO4J_URI}",
        "NEO4J_USERNAME": "${NEO4J_USERNAME}",
        "NEO4J_PASSWORD": "${NEO4J_PASSWORD}",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_READ_ONLY": "true"
      }
    }
  }
}

Cline — ~/.vscode/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json (same structure as Claude Code, uses mcpServers). Or add via VS Code settings → Cline extension → MCP Servers panel.

Antigravity — mcp_config.json at project root (same structure as Claude Code, uses mcpServers).

Step 4 — Restart the editor

After editing the config file, restart the editor (or reload the MCP server if the editor supports hot-reload). Verify the server appears in the editor's MCP panel or tool list.

Step 5 — Smoke test

Run get-schema via the agent or directly via MCP. Do not use "does it return labels?" as the test — an empty database returns no labels and looks identical to a broken connection.

Use this instead — it succeeds even on an empty DB:

read-cypher: RETURN 'connected' AS status

Expected: { "status": "connected" }. Any result confirms the server is alive and the credentials are valid.

If the database has data, also run:

get-schema

and confirm it returns the node labels and relationship types you expect.

HTTP Transport

HTTP transport runs the MCP server as a persistent network service — useful for shared servers, containers, or multiple clients.

# With credentials baked in (simpler — server authenticates all clients as the same user)
neo4j-mcp \
  --neo4j-transport-mode http \
  --neo4j-http-host 127.0.0.1 \
  --neo4j-http-port 8080 \
  --neo4j-uri bolt://localhost:7687 \
  --neo4j-username neo4j \
  --neo4j-password <password> \
  --neo4j-database neo4j

Editor config for HTTP (no credentials in config — server holds them):

{
  "mcpServers": {
    "neo4j-http": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

Per-request auth (omit --neo4j-username/--neo4j-password from the server command): each client request must include an Authorization: Basic <base64(username:password)> header. Generate the value with:

echo -n "neo4j:<password>" | base64

Then add to the editor config:

{
  "headers": { "Authorization": "Basic bmVvNGo6cGFzc3dvcmQ=" }
}

> Security: bind to 127.0.0.1, not 0.0.0.0. Only change to a broader interface if you need remote access and have TLS + auth in front of it.

Environment Variables

| Variable | Required | Default | Notes |

|---|---|---|---|

| NEO4J_URI | yes | — | neo4j+s:// for Aura; bolt:// for local |

| NEO4J_USERNAME | yes | — | |

| NEO4J_PASSWORD | yes | — | |

| NEO4J_DATABASE | no | server default | Specify explicitly to avoid routing to wrong DB |

| NEO4J_READ_ONLY | no | false | Set true to hide write-cypher (safe default for exploration) |

When to set NEO4J_READ_ONLY=false (or remove the variable): any use case that needs to write data — imports, MERGE, schema changes, GDS write-back. Without write access, the agent will see only three tools (get-schema, read-cypher, list-gds-procedures) and write-cypher calls will fail.

APOC Requirement

The MCP server uses APOC for schema introspection (get-schema). On Aura, APOC is included automatically. On self-managed Neo4j, install the APOC plugin and whitelist it:

# neo4j.conf
dbms.security.procedures.unrestricted=apoc.*

Verify: read-cypher: RETURN apoc.version() AS v — if this fails, get-schema will return incomplete results.

Troubleshooting

| Symptom | Likely cause | Fix |

|---|---|---|

| Server not listed in editor | Config file path wrong, JSON malformed, or editor not restarted | Validate JSON (python3 -m json.tool settings.json); confirm correct file for your editor; restart editor |

| neo4j-mcp: command not found | Editor PATH doesn't include the binary location | Use absolute path in command: run which neo4j-mcp in terminal and paste the result |

| Server starts then immediately exits | Python not found (pip install) or wrong binary for OS (binary install) | Run the command manually in terminal to see the error: /full/path/neo4j-mcp --version |

| AuthenticationException | Wrong credentials | Verify URI + credentials with cypher-shell or driver before editing config |

| write-cypher tool missing | NEO4J_READ_ONLY=true | Remove or set to false if writes are needed |

| ServiceUnavailable | DB not reachable from editor process | Check firewall, VPN, or whether Aura instance is paused |

| list-gds-procedures returns empty | GDS not installed or Aura Free | GDS requires Aura Professional/Enterprise or self-managed with plugin |

Checklist

• [ ] which neo4j-mcp run and absolute path noted — this goes in command, not neo4j-mcp
• [ ] Connectivity verified (RETURN 'connected') before editing editor config
• [ ] Credentials not committed to git; .env in .gitignore
• [ ] NEO4J_READ_ONLY set intentionally — true for exploration, false/absent for write use cases
• [ ] NEO4J_DATABASE specified explicitly
• [ ] Correct config file used for the target editor (VS Code uses servers; all others use mcpServers)
• [ ] Config is valid JSON (validate with python3 -m json.tool <file> before saving)
• [ ] Editor restarted after config change
• [ ] Smoke test passed: read-cypher: RETURN 'connected' AS status returns a result
• [ ] APOC available on self-managed: read-cypher: RETURN apoc.version()

References

• MCP Server Docs
• MCP GitHub
• All Neo4j MCP Servers
• GraphAcademy: Developing with Neo4j MCP Tools