The Neo4j Cypher MCP Server is a useful tool for developers and non-technical users alike. It provides an LLM with the ability to read and write data to a Neo4j database.
In this lesson, you will learn how to use the three tools provided by the Neo4j Cypher MCP Server to interact with Neo4j databases through natural language.
Setting up agent mode
To use MCP tools, the server will need to be running and you need to be in Agent mode in the Copilot chat window.
To start your MCP server:
-
Open the Command Palette (Ctrl+Shift+P)
-
Select MCP: List Servers
-
Select the Neo4j Cypher server
-
Select Start Server
Or alternatively, you can open .vscode/mcp.json and click the Start button that appears above the server in the UI.
Once the server is running, open Copilot chat window in VS Code:
-
Go to the File menu → View → Chat
-
Open the Command Palette (Ctrl+Shift+P) and select
Chat: Focus on Chat view -
Select Agent mode in the bottom left corner
Agent mode allows Copilot to use the MCP tools to answer your questions about the database.
Understanding the database schema
The first tool you’ll use is get-neo4j-schema.
This tool solves a common problem with AI-generated database queries: LLMs have been known to invent the label names, properties, or relationship types that don’t exist in your actual database.
The get-neo4j-schema tool lets the AI discover what’s actually in your Neo4j database before writing queries.
You can invoke the tool by asking a question about the database schema. For example:
-
Describe the data model
-
What node labels and relationship types are available in the database?
-
How are <label 1> and <label 2> related?
The tool has no input, and returns a JSON object that describes the schema of the database.
Example schema output
[
{
"label": "Movie",
"attributes": {
"budget": "INTEGER",
"movieId": "STRING unique indexed",
"tmdbId": "STRING unique indexed",
"imdbVotes": "INTEGER",
"runtime": "INTEGER",
"countries": "LIST",
"imdbId": "STRING indexed",
"url": "STRING",
"plot": "STRING",
"released": "STRING indexed",
"languages": "LIST",
"imdbRating": "FLOAT indexed",
"title": "STRING indexed",
"poster": "STRING",
"year": "INTEGER indexed",
"revenue": "INTEGER"
},
"relationships": {
"IN_GENRE": "Genre"
}
},
{
"label": "Genre",
"attributes": {
"name": "STRING unique indexed"
},
"relationships": {}
},
{
"label": "User",
"attributes": {
"name": "STRING indexed",
"userId": "STRING unique indexed"
},
"relationships": {
"RATED": "Movie"
}
},
{
"label": "Actor",
"attributes": {
"born": "DATE",
"bornIn": "STRING",
"tmdbId": "STRING",
"bio": "STRING",
"died": "DATE",
"name": "STRING",
"poster": "STRING",
"imdbId": "STRING",
"url": "STRING"
},
"relationships": {
"ACTED_IN": "Movie",
"DIRECTED": "Movie"
}
},
{
"label": "Director",
"attributes": {
"born": "DATE",
"bornIn": "STRING",
"tmdbId": "STRING",
"bio": "STRING",
"died": "DATE",
"name": "STRING",
"poster": "STRING",
"imdbId": "STRING",
"url": "STRING"
},
"relationships": {
"ACTED_IN": "Movie",
"DIRECTED": "Movie"
}
},
{
"label": "Person",
"attributes": {
"born": "DATE",
"bornIn": "STRING",
"tmdbId": "STRING unique indexed",
"bio": "STRING",
"died": "DATE",
"name": "STRING indexed",
"poster": "STRING",
"imdbId": "STRING",
"url": "STRING"
},
"relationships": {
"ACTED_IN": "Movie",
"DIRECTED": "Movie"
}
}
]Reading data safely
The read-neo4j-cypher tool is used to read data from the database. It does not have permissions to create, update, or delete data.
You can invoke the tool by asking a question about the data in the database. For example:
-
What are the top 10 movies by revenue?
-
Who directed the movie "The Matrix"?
This method has two benefits. Firstly, it adheres to the routing policy of the Neo4j server, directing queries across servers in a Neo4j cluster. Secondly, as the query is executed within a read transaction, the tool is not capable of performing potentially destructive actions.
This means you can approve the tool to always run without permission, knowing that it will not delete or modify any data.
What are the top 10 movies by revenue?
Input:
{
"query": "MATCH (m:Movie) WHERE m.revenue IS NOT NULL RETURN m.title AS title, m.revenue AS revenue ORDER BY m.revenue DESC LIMIT 10"
}Output:
The top 10 movies by revenue in your Neo4j database are:
1. Avatar
2. Titanic
3. Star Wars: Episode VII - The Force Awakens
4. Jurassic World
5. The Avengers
6. Furious 7
7. Avengers: Age of Ultron
8. Harry Potter and the Deathly Hallows: Part 2
9. Frozen
10. Iron Man 3Because this tool only reads data, many AI hosts will run it automatically without asking for permission.
Writing data with approval
The write-neo4j-cypher tool allows an agent to write data to the Neo4j database.
This tool can create, update, or delete data in your database. It’s perfect for non-technical users who want to modify data using natural language instead of learning Cypher.
This tool will be invoked with a question about creating or modifying data. For example:
-
Create a new user named Sarah
-
Add a 5-star rating from John to The Godfather
Conversational writes
Most AI hosts will ask for permission before running this tool, showing you the generated Cypher so you can review it first.
Where this fits
These three tools work together to create a complete database interaction experience.
The schema tool prevents hallucinations, the read tool explores data safely, and the write tool makes changes with your approval.
This combination allows anyone to work with Neo4j databases using natural language, while maintaining safety and accuracy.
What’s next
Now that you understand how the Neo4j MCP tools work, you’re ready to try them yourself.
In the next lesson, you’ll use these tools to explore and modify a movie recommendation database.
Check your understanding
Tool Safety and Permissions
Why might the read-neo4j-cypher tool be considered safer to run without explicit approval compared to the write-neo4j-cypher tool?
Select the correct answer:
-
❏ The read tool has better error handling than the write tool
-
❏ The read tool only works with small datasets
-
✓ The read tool executes within read transactions and cannot modify data
-
❏ The read tool requires authentication while the write tool does not
-
❏ The read tool is faster than the write tool
Hint
Think about the fundamental difference between reading and writing data. Consider what protections are built into each tool at the transaction level.
The lesson mentions two specific benefits of the read tool: 1. It adheres to routing policy in Neo4j clusters 2. It provides a safety guarantee about data modification
Which of these relates to why it might be considered safer to auto-approve?
Solution
The correct answer is The read tool executes within read transactions and cannot modify data.
The read-neo4j-cypher tool can be considered safer for auto-approval because it executes queries within read transactions. This provides a fundamental safety guarantee - read transactions cannot perform write operations like CREATE, MERGE, SET or DELETE.
Even if an LLM generates a potentially destructive Cypher statement, the driver will block these operations from running in read mode.
Summary
The Neo4j Cypher MCP Server provides three tools for natural language database interaction:
-
get-neo4j-schema- Obtains the database schema to prevent AI hallucinations -
read-neo4j-cypher- Executes safe, read-only queries automatically -
write-neo4j-cypher- Modifies data with user approval for safety
These tools let anyone interact with Neo4j databases using natural language while maintaining safety through read-only operations and approval workflows.