neo4j-mcp-skill
installsforks
How to install neo4j-mcp-skill?
neo4j-contrib/neo4j-skills/neo4j-mcp-skill
$npx -y skills add neo4j-contrib/neo4j-skills --skill neo4j-mcp-skillUse when installing, configuring, or troubleshooting the official Neo4j MCP server
SKILL.md
| 1 | # Neo4j MCP Skill |
| 2 | |
| 3 | Installs and configures the [official Neo4j MCP server](https://github.com/neo4j/mcp) so AI agents can connect to Neo4j via any MCP-compatible client. |
| 4 | |
| 5 | ## When to Use |
| 6 | |
| 7 | - Connecting Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Kiro, or another editor to Neo4j via MCP |
| 8 | - Installing `neo4j-mcp-server` and writing the correct config for a specific editor |
| 9 | - Switching between stdio and HTTP transport |
| 10 | - Enabling or disabling write access (`NEO4J_READ_ONLY`) |
| 11 | - Troubleshooting "MCP server not found" or connection errors |
| 12 | |
| 13 | ## When NOT to Use |
| 14 | |
| 15 | - **Writing or optimizing Cypher queries** → use `neo4j-cypher-skill` |
| 16 | - **Provisioning a new Neo4j Aura instance** → use `neo4j-aura-provisioning-skill` |
| 17 | - **Agent long-term memory** → use `neo4j-agent-memory-skill` |
| 18 | - **neo4j-admin / cypher-shell / aura-cli** → use `neo4j-cli-tools-skill` |
| 19 | |
| 20 | --- |
| 21 | |
| 22 | ## Available MCP Tools |
| 23 | |
| 24 | | Tool | Type | What it does | |
| 25 | |---|---|---| |
| 26 | | `get-schema` | read | Returns labels, relationship types, property keys, and indexes | |
| 27 | | `read-cypher` | read | Executes read-only Cypher (`MATCH`, `RETURN`, `SHOW`) | |
| 28 | | `write-cypher` | write | Executes write Cypher (`MERGE`, `CREATE`, `SET`, `DELETE`) — disabled when `NEO4J_READ_ONLY=true` | |
| 29 | | `list-gds-procedures` | read | Lists available Graph Data Science procedures (requires GDS plugin) | |
| 30 | |
| 31 | --- |
| 32 | |
| 33 | ## Installation |
| 34 | |
| 35 | ### Step 1 — Install and find the absolute path |
| 36 | |
| 37 | ```bash |
| 38 | # Option A: pip (recommended) |
| 39 | pip install neo4j-mcp-server |
| 40 | |
| 41 | # Option B: Download binary |
| 42 | # https://github.com/neo4j/mcp/releases -- macOS, Linux, Windows binaries |
| 43 | |
| 44 | # Option C: Docker |
| 45 | docker pull neo4j/mcp |
| 46 | ``` |
| 47 | |
| 48 | **Get the absolute path — you will need this in Step 3:** |
| 49 | ```bash |
| 50 | which neo4j-mcp # e.g. /usr/local/bin/neo4j-mcp |
| 51 | # or: /Users/you/project/.venv/bin/neo4j-mcp (if installed in venv) |
| 52 | |
| 53 | neo4j-mcp --version # confirm it runs |
| 54 | ``` |
| 55 | |
| 56 | > **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. |
| 57 | |
| 58 | ### Step 2 — Prepare credentials |
| 59 | |
| 60 | ```bash |
| 61 | # .env (gitignored) |
| 62 | NEO4J_URI=neo4j+s://<instance>.databases.neo4j.io # Aura |
| 63 | # or bolt://localhost:7687 # local |
| 64 | NEO4J_USERNAME=neo4j |
| 65 | NEO4J_PASSWORD=<password> |
| 66 | NEO4J_DATABASE=neo4j |
| 67 | ``` |
| 68 | |
| 69 | Verify connectivity before configuring the editor: |
| 70 | ```bash |
| 71 | source .env |
| 72 | cypher-shell -a "$NEO4J_URI" -u "$NEO4J_USERNAME" -p "$NEO4J_PASSWORD" \ |
| 73 | "RETURN 'connected' AS status" |
| 74 | # If cypher-shell not available: python3 -c " |
| 75 | # from neo4j import GraphDatabase, __version__ |
| 76 | # d = GraphDatabase.driver('$NEO4J_URI', auth=('$NEO4J_USERNAME','$NEO4J_PASSWORD')) |
| 77 | # d.verify_connectivity(); print('connected'); d.close()" |
| 78 | ``` |
| 79 | |
| 80 | ### Step 3 — Configure your editor |
| 81 | |
| 82 | Pick the config block for your editor. All use STDIO transport (the MCP server runs as a subprocess of the editor). |
| 83 | |
| 84 | **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. |
| 85 | |
| 86 | ```json |
| 87 | { |
| 88 | "mcpServers": { |
| 89 | "neo4j": { |
| 90 | "command": "/full/path/to/neo4j-mcp", |
| 91 | "env": { |
| 92 | "NEO4J_URI": "neo4j+s://<host>", |
| 93 | "NEO4J_USERNAME": "neo4j", |
| 94 | "NEO4J_PASSWORD": "<password>", |
| 95 | "NEO4J_DATABASE": "neo4j", |
| 96 | "NEO4J_READ_ONLY": "true" |
| 97 | } |
| 98 | } |
| 99 | } |
| 100 | } |
| 101 | ``` |
| 102 | |
| 103 | CLI alternative (sets command only — you still need to add env vars to the file): |
| 104 | ```bash |
| 105 | claude mcp add neo4j /full/path/to/neo4j-mcp |
| 106 | ``` |
| 107 | |
| 108 | **Claude Desktop** |
| 109 | - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` |
| 110 | - Windows: `%APPDATA%\Claude\claude_desktop_config.json` |
| 111 | |
| 112 | ```json |
| 113 | { |
| 114 | "mcpServers": { |
| 115 | "neo4j": { |
| 116 | "command": "/full/path/to/neo4j-mcp", |
| 117 | "env": { |
| 118 | "NEO4J_URI": "neo4j+s://<host>", |
| 119 | "NEO4J_USERNAME": "neo4j", |
| 120 | "NEO4J_PASSWORD": "<password>", |
| 121 | "NEO4J_DATABASE": "neo4j", |
| 122 | "NEO4J_READ_ONLY": "true" |
| 123 | } |
| 124 | } |
| 125 | } |
| 126 | } |
| 127 | ``` |
| 128 | |
| 129 | **VS Code** — `.vscode/mcp.json` (note: uses `servers`, not `mcpServers` — diffe |
People who liked this also viewed
6 picksType
- azure-storageAzure Storage Services including Blob Storage, File Shares, Queue Storage, Table Storage, and Data Lake. Answers questions about storage access tiers (hot, cool, cold, archive), when to use each tier,SkillsJul 2026
- supabase-postgres-best-practicesPostgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.SkillsJul 2026
- supabaseUse when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries and SSR integrations (supabase-js, SkillsJul 2026
- convex-quickstartCreates or adds Convex to an app. Use for new Convex projects, npm create convex@latest, frontend setup, env vars, or the first npx convex dev run.SkillsJul 2026
- convex-performance-auditAudits Convex performance for reads, subscriptions, write contention, and function limits. Use for slow features, insights findings, OCC conflicts, or read amplification.SkillsJul 2026
- convex-setup-authSets up Convex auth, identity mapping, and access control. Use for login, auth providers, users tables, protected functions, or roles in a Convex app.SkillsJul 2026
