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
References