# Neo4j Mcp Skill

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

- **Type:** Skill
- **Install:** `agentstack add skill-neo4j-contrib-neo4j-skills-neo4j-mcp-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [neo4j-contrib](https://agentstack.voostack.com/s/neo4j-contrib)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [neo4j-contrib](https://github.com/neo4j-contrib)
- **Source:** https://github.com/neo4j-contrib/neo4j-skills/tree/main/neo4j-mcp-skill
- **Website:** https://neo4j.com/llms.txt

## Install

```sh
agentstack add skill-neo4j-contrib-neo4j-skills-neo4j-mcp-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Neo4j MCP Skill

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.

## 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

```bash
# 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:**
```bash
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

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

Verify connectivity before configuring the editor:
```bash
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.

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

CLI alternative (sets command only — you still need to add env vars to the file):
```bash
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`

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

**VS Code** — `.vscode/mcp.json` (note: uses `servers`, not `mcpServers` — different from all other editors):
```json
{
  "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:
```json
{
  "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.

```bash
# 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  \
  --neo4j-database neo4j
```

Editor config for HTTP (no credentials in config — server holds them):
```json
{
  "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 ` header. Generate the value with:
```bash
echo -n "neo4j:" | base64
```
Then add to the editor config:
```json
{
  "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 ` 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](https://neo4j.com/docs/mcp/)
- [MCP GitHub](https://github.com/neo4j/mcp)
- [All Neo4j MCP Servers](https://neo4j.com/developer/genai-ecosystem/model-context-protocol-mcp/)
- [GraphAcademy: Developing with Neo4j MCP Tools](https://graphacademy.neo4j.com/courses/genai-mcp-neo4j-tools/)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [neo4j-contrib](https://github.com/neo4j-contrib)
- **Source:** [neo4j-contrib/neo4j-skills](https://github.com/neo4j-contrib/neo4j-skills)
- **License:** MIT
- **Homepage:** https://neo4j.com/llms.txt

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-neo4j-contrib-neo4j-skills-neo4j-mcp-skill
- Seller: https://agentstack.voostack.com/s/neo4j-contrib
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.