Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
AI & knowledge

neo4j-mcp-skill

Use when installing, configuring, or troubleshooting the official Neo4j MCP server

neo4j-contrib · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add neo4j-contrib/neo4j-skills --skill neo4j-mcp-skill

About this skill


name: neo4j-mcp-skill description: Use when installing, configuring, or troubleshooting the official Neo4j MCP server (neo4j/mcp) — connecting Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Kiro, or other MCP-compatible editors to a Neo4j database via stdio or HTTP transport. Covers the four MCP tools (get-schema, read-cypher, write-cypher, list-gds-procedures), read-only mode, and multi-database configuration. Does NOT cover writing Cypher queries via those tools — use neo4j-cypher-skill. Does NOT cover agent memory — use neo4j-agent-memory-skill. Does NOT cover Aura instance provisioning — use neo4j-aura-provisioning-skill. allowed-tools: Bash, WebFetch version: 1.0.2

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

ToolTypeWhat it does
get-schemareadReturns labels, relationship types, property keys, and indexes
read-cypherreadExecutes read-only Cypher (MATCH, RETURN, SHOW)
write-cypherwriteExecutes write Cypher (MERGE, CREATE, SET, DELETE) — disabled when NEO4J_READ_ONLY=true
list-gds-proceduresreadLists 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_US
Read the complete source ↗