name	neo4j-cypher
description	Expert guidance for Neo4j Cypher queries and MCP server tools. Use when working with mcp__neo4j__ tools for query execution, schema introspection, and graph operations.

Master the Neo4j MCP (Model Context Protocol) server tools for efficient graph database development. These tools provide direct integration with Neo4j databases, enabling query execution, schema introspection, and graph exploration without manual connection management. **Execute Cypher queries:** ``` mcp__neo4j__get_schema → Understand structure mcp__neo4j__execute_query → Run Cypher ```

Explore graph schema:

mcp__neo4j__get_schema → Get labels, relationships, constraints

Data modeling workflow:

mcp__neo4j__get_schema → Current state
[design changes]
mcp__neo4j__execute_query → Apply constraints/indexes
mcp__neo4j__get_schema → Verify changes

**Core Neo4j MCP Tools:**

Tool	Purpose	When to Use
`mcp__neo4j__execute_query`	Execute Cypher queries (read/write)	All database operations
`mcp__neo4j__get_schema`	Get database schema (labels, relationships, constraints)	Before writing queries, understanding structure

Tool Usage:

mcp__neo4j__get_schema
→ Returns: node labels, relationship types, property keys, constraints, indexes

mcp__neo4j__execute_query
→ Input: Cypher query string
→ Returns: Query results as JSON

Best Practices:

ALWAYS call get_schema before writing complex queries
Use schema info to validate label/relationship names
Check for existing constraints before creating new ones
Verify indexes exist for query predicates

**Additional Neo4j MCP Servers (if available):**

Server	Purpose
`mcp-neo4j-cypher`	Query execution with natural language support
`mcp-neo4j-memory`	Knowledge graph storage across sessions
`mcp-neo4j-aura`	Aura cloud instance management
`mcp-neo4j-modeler`	Data model validation and visualization

Check available tools with your MCP client to see which servers are configured.

**Query Development Workflow:**

1. Get schema context
   mcp__neo4j__get_schema → Understand labels, relationships

2. Write query using correct names
   - Use exact label names from schema
   - Use correct relationship types
   - Reference indexed properties

3. Execute query
   mcp__neo4j__execute_query → Run Cypher

4. Verify results
   - Check returned structure
   - Validate data types

**Schema Change Workflow:**

1. Check current state
   mcp__neo4j__get_schema → Current constraints/indexes

2. Apply changes
   mcp__neo4j__execute_query → CREATE CONSTRAINT/INDEX

3. Verify changes
   mcp__neo4j__get_schema → Confirm new constraints

## Node Patterns

(n)                          -- Any node
(n:Label)                    -- Node with label
(n:Label {prop: value})      -- Node with property
(n:Label:OtherLabel)         -- Multiple labels

Relationship Patterns

-[r]->                       -- Directed relationship
-[r:TYPE]->                  -- With type
-[r:TYPE {prop: value}]->    -- With property
-[r:TYPE*1..3]->             -- Variable length (1-3 hops)
-[r]- or -[r]-               -- Undirected

CRUD Operations

-- Create
CREATE (n:Person {name: 'Alice'})
CREATE (a)-[:KNOWS]->(b)

-- Read
MATCH (n:Person) RETURN n
MATCH (a)-[:KNOWS]->(b) RETURN a, b

-- Update
MATCH (n:Person {name: 'Alice'})
SET n.age = 30

-- Delete
MATCH (n:Person {name: 'Alice'})
DETACH DELETE n

Merge (Idempotent Create)

MERGE (n:Person {id: $id})
ON CREATE SET n.created = datetime()
ON MATCH SET n.updated = datetime()

Filtering

WHERE n.age > 18
WHERE n.name STARTS WITH 'A'
WHERE n.name CONTAINS 'ice'
WHERE n.status IN ['active', 'pending']
WHERE (n)-[:KNOWS]->()
WHERE NOT EXISTS { (n)-[:BLOCKED]->() }

Aggregations

count(n)
sum(n.value)
avg(n.value)
collect(n.name)           -- List
min(n.value), max(n.value)

Path Queries

-- Shortest path
MATCH path = shortestPath((a)-[*]-(b))
RETURN path

-- All shortest paths
MATCH path = allShortestPaths((a)-[*]-(b))
RETURN path

Common Clauses

WITH      -- Chain queries, aggregate
ORDER BY  -- Sort results
LIMIT     -- Limit results
SKIP      -- Offset results
UNWIND    -- Expand list to rows
UNION     -- Combine result sets

Indexes and Constraints

-- Index
CREATE INDEX idx_name FOR (n:Label) ON (n.prop)

-- Unique constraint
CREATE CONSTRAINT unique_email
FOR (u:User) REQUIRE u.email IS UNIQUE

-- Existence constraint
CREATE CONSTRAINT email_exists
FOR (u:User) REQUIRE u.email IS NOT NULL

Parameters

-- Always use parameters (not string interpolation)
MATCH (u:User {email: $email})
RETURN u

Useful Functions

-- String
toLower(), toUpper(), trim(), split()

-- Type conversion
toInteger(), toFloat(), toString()

-- Date/Time
date(), datetime(), time(), duration()

-- Collections
size(), head(), tail(), range()

-- Aggregation
count(), sum(), avg(), collect()

**Common Mistakes:**

Guessing label names → Always check schema first
Skipping schema validation → Queries fail on wrong names
Not checking indexes → Slow queries without index hints
Ignoring constraints → Duplicate data issues

Correct Order:

mcp__neo4j__get_schema → [write query] → mcp__neo4j__execute_query → [verify]

MCP tool usage is correct when:

get_schema called before writing queries to unknown databases
Query uses exact label/relationship names from schema
Constraints verified before data modifications
Results validated against expected structure

Uncertainty Handling:

If schema is unclear, call get_schema again
If query fails, check error message for typos in names
NEVER guess at label or relationship names

neo4j-cypher

Install Skill

SKILL.md