neo4j-cypher

---

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.

<quick_start> <common_workflows> 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

</common_workflows> </quick_start>

<mcp_tools> <neo4j_mcp_tools> 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 </neo4j_mcp_tools>

<advanced_mcp_servers> 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. </advanced_mcp_servers> </mcp_tools>

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

</query_workflow>

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

</schema_change_workflow>

<cypher_reference>

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()

</cypher_reference>

<anti_patterns> 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]

</anti_patterns>

<success_criteria> 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 </success_criteria>