Neo4j MCP — Use Cases, Install & Live Demo

Why use it

Key features

Execute arbitrary Cypher read or write queries
Schema introspection: labels, relationship types, property keys, constraints, indexes
Works against Neo4j Community, Enterprise, AuraDB, and Neo4j Desktop
Separate Aura-admin server for provisioning instances in Neo4j Aura
Small, focused tool surface — no magic; you control every Cypher

Live Demo

What it looks like in practice

neo4j.replay ▶ ready

0/0

Install

Pick your client

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

{
  "mcpServers": {
    "neo4j": {
      "command": "uvx",
      "args": [
        "mcp-neo4j-cypher"
      ]
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "neo4j": {
      "command": "uvx",
      "args": [
        "mcp-neo4j-cypher"
      ]
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "neo4j": {
      "command": "uvx",
      "args": [
        "mcp-neo4j-cypher"
      ]
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "neo4j": {
      "command": "uvx",
      "args": [
        "mcp-neo4j-cypher"
      ]
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "neo4j",
      "command": "uvx",
      "args": [
        "mcp-neo4j-cypher"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "neo4j": {
      "command": {
        "path": "uvx",
        "args": [
          "mcp-neo4j-cypher"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add neo4j -- uvx mcp-neo4j-cypher

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use Neo4j

Explore an unfamiliar graph schema in 5 minutes

👤 Engineers / analysts inheriting a Neo4j DB ⏱ ~15 min beginner

When to use: You got handed a graph DB with no docs. You need a mental model before you can write useful queries.

Prerequisites

Neo4j Bolt URL + user/password — NEO4J_URI=bolt://host:7687, NEO4J_USERNAME, NEO4J_PASSWORD
Read-only user recommended for exploration — CREATE USER claude SET PASSWORD '...' SET ROLES reader

Flow

Get schema overview

Call get_neo4j_schema. Summarize node labels, relationship types, and the most common (label)-[rel]->(label) patterns.✓ Copied

→ Schema summary with sample triples
Sample representative nodes

For the 3 most common labels, MATCH (n:Label) RETURN n LIMIT 3 each. Describe what each label seems to represent.✓ Copied

→ Semantic descriptions of labels
Draw the likely ER model

Based on schema + samples, describe in prose the 'entity' story of this graph. What's the main object, what connects to it, what's peripheral?✓ Copied

→ Clear domain model description

Outcome: A one-page domain model you can validate with the original authors.

Pitfalls

Sampling tiny graphs gives misleading patterns — Also MATCH (n)-[r]->() RETURN type(r), count(*) to see which rels dominate

Combine with: filesystem

Write graph queries to detect fraud rings

👤 Risk / fraud analysts ⏱ ~40 min advanced

When to use: You suspect shared-device or shared-address fraud rings across accounts.

Prerequisites

Graph with User, Device, Address, Payment nodes and :USED, :LIVES_AT, :PAID relationships — Typical fraud-graph shape

Flow

Find shared devices

Find devices used by 3+ different users in the last 30 days. Return device_id + list of user_ids + last-used ts per pair.✓ Copied

→ Ring candidates
Score by connected-component size

Using GDS or pure Cypher, compute connected components over User-(:USED)-Device-(:USED)-User. Return top 10 components by size.✓ Copied

→ Suspicious clusters
Produce an actionable list

For each top cluster, list distinct users, total transaction volume, and earliest/latest activity. Flag clusters > $10k as high-priority review.✓ Copied

→ Analyst queue entries

Outcome: A prioritized fraud-review queue with the exact Cypher preserved.

Pitfalls

Naïve traversals blow up on hubs (shared public wifi device with 10k users) — Cap depth and filter out hub nodes by degree before traversing

Combine with: postgres

Prototype a content recommendation query

👤 Product engineers building 'users who also liked' ⏱ ~30 min intermediate

When to use: You have User-LIKED->Item and want to recommend items from similar users.

Flow

Pick a user and find neighbors

For user <id>, find 20 users who share the most LIKED items. Return user_id and overlap count.✓ Copied

→ Similar users ranked
Recommend items those users liked

For those top 20 similar users, list items they liked that <id> has NOT liked. Rank by number of similar users who liked it.✓ Copied

→ Top-N recommendations
Turn it into a reusable query

Parameterize as a callable Cypher with $user_id; add indexes needed for speed.✓ Copied

→ Production-ready query + CREATE INDEX statements

Outcome: A working collaborative-filtering query, fast enough to serve online.

Pitfalls

Forgetting an index on :User(id) makes startup queries linear — CREATE INDEX FOR (u:User) ON (u.id) and EXPLAIN to confirm it's used

Load relational data into Neo4j from a staging table

👤 Data engineers moving from SQL to graph ⏱ ~40 min advanced

When to use: You have users + follows in Postgres and want a graph representation.

Prerequisites

Writable Neo4j user — Role with CREATE on the target database

Flow

Plan the node/edge mapping

Given tables users(id, name) and follows(from_id, to_id), propose the Neo4j model. Label(s)? Relationship direction?✓ Copied

→ (:User {id,name})-[:FOLLOWS]->(:User)
Create constraints first

Generate CREATE CONSTRAINT FOR (u:User) REQUIRE u.id IS UNIQUE. Run it.✓ Copied

→ Constraint created
Bulk load with MERGE

From the provided user rows, run UNWIND $rows AS r MERGE (:User {id:r.id}) ... then follows with MERGE (a)-[:FOLLOWS]->(b). Batch 10k at a time.✓ Copied

→ All rows loaded idempotently

Outcome: A re-runnable ETL that loads your relational data into a graph shape.

Pitfalls

CREATE instead of MERGE creates duplicate nodes on re-run — Always MERGE for upserts, and require a uniqueness constraint before bulk MERGE for speed

Combine with: postgres

Answer natural-language questions over a knowledge graph

👤 Internal teams with a domain KG ⏱ ~25 min intermediate

When to use: You built a small ontology (products, features, customers) and want Claude to answer 'which customers use feature X' without learning Cypher.

Flow

Ground Claude in the schema

Here's the schema [paste get_neo4j_schema output]. From now on, translate my questions to Cypher before running them.✓ Copied

→ Claude echoes the schema understanding
Ask a question, get Cypher + answer

Which customers use feature 'export-csv' in the last quarter?✓ Copied

→ Cypher shown + result table
Refine when Cypher is wrong

That Cypher missed the :USED relationship to Session. Fix it to go through sessions.✓ Copied

→ Corrected Cypher re-run

Outcome: A lightweight NL-to-Cypher interface for non-technical teammates.

Pitfalls

Claude invents labels that don't exist — Pin it: 'only use labels/rels from the provided schema; otherwise say unknown'

Combinations

Pair with other MCPs for X10 leverage

neo4j + postgres

Sync relational data to a graph representation

Pull users + follows from Postgres, then MERGE into Neo4j as (:User)-[:FOLLOWS]->(:User).✓ Copied

neo4j + qdrant

Graph-enhanced RAG: use Qdrant for semantic recall, Neo4j for precise relationships

Qdrant finds docs similar to the question; then traverse Neo4j from matched entities to pull structured facts for the answer.✓ Copied

neo4j + filesystem

Export a Cypher-generated report as CSV/Markdown

Run the fraud-ring Cypher, export top 50 clusters as /reports/fraud-<date>.csv.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
get_neo4j_schema		Always first in a new session	free
read_neo4j_cypher	query: str, params?: object	Any MATCH / RETURN — read-only	free
write_neo4j_cypher	query: str, params?: object	CREATE/MERGE/SET/DELETE — mutations	free

Cost & Limits

What this costs to run

API quota: Bounded by your Neo4j instance. Aura Free: 200k nodes/400k rels.
Tokens per call: Schema: ~500 tokens. Query results: depends on rows+properties.
Monetary: Free for Community / self-hosted. Aura Free tier exists. Aura paid from ~$65/mo.
Tip: Always EXPLAIN first on large graphs; a missing index on a startup label turns a 5ms query into a 5min scan.

Security

Permissions, secrets, blast radius

Minimum scopes: reader role for read-only exploration

Credential storage: NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD in env

Data egress: Direct Bolt connection to your Neo4j (self-hosted or Aura)

Never grant: admin role PUBLIC write access

DROP DATABASE and CREATE CONSTRAINT require elevated roles — keep those on a separate admin-only connection profile.
Run the MCP with a reader-role account for any session that doesn't explicitly need to write.

Troubleshooting

Common errors and fixes

ServiceUnavailable: Connection refused

Neo4j not running or wrong Bolt port (default 7687). Check with cypher-shell -a bolt://host:7687.

Verify: nc -zv host 7687

Neo.ClientError.Security.Unauthorized

Wrong username/password. Reset via CALL dbms.security.changePassword('new') from an admin session.

Neo.ClientError.Statement.SyntaxError

Claude's Cypher has a typo — paste the exact error, ask for a corrected query.

Writes fail: Write operation not allowed in read-only mode

You're connected with a reader role; switch to a user with WRITE or use a separate writer connection.

Alternatives

Neo4j vs others

Alternative	When to use it instead	Tradeoff
Memgraph MCP	You need streaming graph analytics; Memgraph is Cypher-compatible	Smaller ecosystem, fewer hosted options
ArangoDB MCP	You want multi-model (graph + document + KV)	AQL instead of Cypher; learning curve
Postgres + Apache AGE	You're mostly relational with some graph needs	Graph performance worse than native Neo4j on large traversals

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills