In the previous lesson, you learned how to configure an MCP server in Claude Desktop.
In this challenge, you will install the Neo4j Cypher MCP server to VS Code and configure it to connect to your Neo4j database.
Get started
The repository, neo4j-graphacademy/genai-mcp-neo4j-tools, has been created for this course. It contains any starter code and resources you need.
You can use a GitHub codespace as an online IDE and workspace for this course. It will automatically clone the course repository and set up your environment.
GitHub Codespaces
You will need to login with a GitHub account. The GitHub Codespaces free monthly usage will cover the duration of this course.
The setup instructions in the README will be open automatically when you open the Codespace.
Your environment variables required for step 2 can be found further down this page.
GitHub Codespace
You can keep the Codespace open while completing the course. You can open your existing codespaces at github.com/codespaces.
Develop on your local machine
You will need:
You may want to set up a virtual environment using venv or virtualenv to keep your dependencies separate from other projects.
Clone the github.com/neo4j-graphacademy/genai-mcp-neo4j-tools repository:
git clone https://github.com/neo4j-graphacademy/genai-mcp-neo4j-toolsInstall uv using pip:
pip install uvYou do not need to create a Neo4j database as you will use the provided sandbox instance.
The sandbox uses Neo4j’s GenAI functions, you can find out more about how to configure them in the Neo4j GenAI integration documentation.
Interacting with Neo4j
To interact with a Neo4j database, we can use the Neo4j Cypher MCP Server. This server is one of a number of MCP servers offered by Neo4j. When configured with environment variables that point to a Neo4j database, the server will enable the host to:
-
Obtain the schema of the database
-
Execute Cypher statements that read and write data to the database
The server is written in Python, so you will use the uvx command to install the server from PyPI and run the server locally, and configure VS Code to communicate with the server using the Standard Input/Output (stdio) transport method.
Step 1: Install the server
To install the Neo4j Cypher MCP server in VS Code, open the .vscode/mcp.json file and add the server configuration:
{
"servers": {
"neo4j-cypher": {
"command": "uvx",
"args": [
"mcp-neo4j-cypher"
]
}
}
}Step 2: Set environment variables
The Neo4j Cypher MCP server will require environment variables to allow it to
-
NEO4J_URI- The connection URI for your Neo4j database (e.g.,neo4j+s://dbid.databases.neo4j.io) -
NEO4J_USERNAME- Your Neo4j username (typicallyneo4j) -
NEO4J_PASSWORD- Your Neo4j password
You can set these variables by adding a new env section to the neo4j-cypher entry in the mcp.json file.
{
"servers": {
"neo4j-cypher": {
"command": "uvx",
"args": [
"mcp-neo4j-cypher"
],
"env": {
"NEO4J_URI": "neo4j+s://dbid.databases.neo4j.io:7687",
"NEO4J_USERNAME": "neo4j",
"NEO4J_PASSWORD": "<your password here>",
"NEO4J_DATABASE": "neo4j"
}
}
}
}You can also use the VS Code MCP: Add Server command to setup the .vscode/mcp.json file, and then add the env section manually.
Verify your installation
To verify that the server is installed correctly, you can use the Command Palette to execute the MCP: List servers command.
You should see a server named neo4j-cypher in the list.
Select the server and then Start Server. VS Code will connect to the server and pull the description of the tools available.
If you ask Copilot which MCP tools are available, you should get a list containing three tools. Open the Copilot chat window by executing the Chat: Open Chat (Agent mode) command in the Command Palette or accessing the three line menu, selecting View and then Chat.
Which MCP tools are available? List their ID and description.
Agent mode
Tools are only available when you use Chat in Agent mode.
Available tools
Which of the following tools are available in Copilot through the Neo4j Cypher MCP server?
Select all that apply:
-
❏
backup-neo4j-database -
❏
create-neo4j-database -
✓
get-neo4j-schema -
✓
read-neo4j-cypher -
❏
validate-cypher-syntax -
✓
write-neo4j-cypher
Hint
You can ask Copilot to list the tools available in the Neo4j Cypher MCP server. Try the following prompt:
Ask Copilot in Agent mode to get a list of available tools.
_What tools are available in the Neo4j Cypher MCP server? List the tool name as it appears on the server and a short description._Solution
The tools available in the Neo4j Cypher MCP server are:
-
get-neo4j-schema - Lists all node labels, their attributes, and relationships in the Neo4j database
-
read-neo4j-cypher - Executes read-only Cypher queries to retrieve data from the database
-
write-neo4j-cypher - Executes write Cypher queries to create, update, or delete data in the database
Summary
In this challenge, you demonstrated how to install an MCP server and configure it with environment variables.
Installing Multiple Neo4j Connections
You can install the Neo4j Cypher MCP server multiple times within the same host using the --namespace option.
{
"mcpServers": {
"movies-neo4j": {
"command": "uvx",
"args": [ "mcp-neo4j-cypher@0.2.3", "--namespace", "movies" ],
"env": {
"NEO4J_URI": "neo4j+s://demo.neo4jlabs.com",
"NEO4J_USERNAME": "recommendations",
"NEO4J_PASSWORD": "recommendations",
"NEO4J_DATABASE": "recommendations"
}
},
"local-neo4j": {
"command": "uvx",
"args": [ "mcp-neo4j-cypher@0.2.3" ],
"env": {
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_USERNAME": "neo4j",
"NEO4J_PASSWORD": "password",
"NEO4J_DATABASE": "neo4j",
"NEO4J_NAMESPACE": "local"
}
}
}
}This configuration will install two Neo4j Cypher MCP servers, one with tools prefixed with movies- for the movies database and one prefixed with local- for the local database.
In the next module, you will explore and understand the full capabilities of the Neo4j Cypher MCP server and its available tools.