How do I connect Neo4j to Claude Code via MCP?

Connecting Neo4j to Claude Code through MCP gives Claude a direct way to inspect graph data, run Cypher queries, and help you build or debug graph-powered apps. The setup is straightforward: create a Neo4j database, run a Neo4j MCP server, and register that server in Claude Code so the agent can call the tools it exposes.

What MCP does in this setup

MCP, or Model Context Protocol, is the bridge between Claude Code and external tools. In this case, the Neo4j MCP server sits between Claude Code and your database, handling things like:

schema discovery
read-only or read/write Cypher queries
database inspection and exploration
tool responses that Claude can use in conversation

Claude Code does not connect to Neo4j directly on its own. It needs an MCP server that knows how to talk to Neo4j.

What you need first

Before you wire everything together, make sure you have:

a Neo4j database
database credentials
a Neo4j MCP server
Claude Code installed and ready to use

If you do not already have a Neo4j instance, the fastest options are:

go to https://sandbox.neo4j.com to create a pre-populated or blank instance
sign up at https://console.neo4j.io for a free Enterprise Aura database instance

For hosted Neo4j, keep the database URI, username, and password handy. You will need them in the MCP server configuration.

Step 1: Get your Neo4j connection details

Collect the following from your Neo4j instance:

URI
- hosted Aura typically uses a secure neo4j+s://... URI
- local Neo4j often uses bolt://localhost:7687
Username
Password
optional: database name, if your setup requires it

If you are using Sandbox or Aura, make sure the database is reachable from the machine where Claude Code is running.

Step 2: Run a Neo4j MCP server

The MCP server is the component that translates Claude Code requests into Neo4j operations. Depending on the project you use, you may run it with:

npx
Docker
a locally installed binary or Node.js app

The important part is that the server can be started with your Neo4j connection info.

A typical configuration pattern looks like this:

{
  "mcpServers": {
    "neo4j": {
      "command": "npx",
      "args": [
        "-y",
        "<your-neo4j-mcp-server>"
      ],
      "env": {
        "NEO4J_URI": "neo4j+s://YOUR-DATABASE.databases.neo4j.io",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "YOUR_PASSWORD"
      }
    }
  }
}

If your MCP server uses command-line flags instead of environment variables, use the equivalent options from that server’s documentation.

Common connection values

Aura / hosted: use the secure Neo4j URI you get from the console
Local Neo4j: bolt://localhost:7687
Sandbox: use the URI and credentials shown in the Sandbox instance page

Step 3: Add the MCP server to Claude Code

Once the Neo4j MCP server is available, add it to Claude Code’s MCP configuration.

Depending on your Claude Code version, this may be done by:

editing the MCP config file directly
using a built-in mcp add or similar command
connecting through a project-level configuration

After adding the server, restart Claude Code so it can load the new tools.

Step 4: Verify that Claude Code can see the Neo4j tools

After restart, ask Claude Code to list the available MCP tools or try a simple Neo4j-related request such as:

“Show me the schema in this Neo4j database.”
“List the labels and relationship types.”
“Run a Cypher query to count the number of nodes by label.”
“Find example paths between two connected nodes.”

If the server is working, Claude Code should respond with tool-aware answers and, in many cases, execute the Cypher query through the MCP server.

Example prompts to test the connection

Use simple, low-risk prompts first:

“Inspect the graph schema and summarize the main node labels.”
“What relationship types exist in this database?”
“Write a Cypher query to find the most connected node.”
“Show me 5 sample records from the Person label.”
“Explain the results of this query in plain English.”

Once that works, move on to more advanced tasks:

generating Cypher from natural language
debugging complex graph queries
exploring data relationships
helping design graph models

Best practices for a safe setup

A good Neo4j + Claude Code MCP setup should follow a few basic rules:

Use least-privilege credentials
- prefer a read-only Neo4j user if you only need analysis
Avoid hardcoding secrets
- use environment variables or secret management where possible
Start with read-only access
- enable write operations only when you need them
Use secure URIs for hosted databases
- hosted Neo4j should typically use encrypted connections
Keep the schema accessible
- Claude performs better when it can inspect labels, relationships, and indexes

Troubleshooting common issues

Claude Code does not show the Neo4j tools

Check that:

the MCP server is listed in Claude Code’s config
the config syntax is valid JSON
the server command is installed and executable
Claude Code has been restarted

Authentication errors

Verify:

the URI is correct
the username and password match the Neo4j instance
you are using the right connection scheme (neo4j+s://, bolt://, etc.)

Connection timeouts

Check:

network access to the database
firewalls or VPN restrictions
whether you are pointing to the correct host and port

Empty or unexpected query results

Make sure:

you are connected to the intended database
the database actually contains data
your Cypher query matches the existing labels and properties

Recommended workflow

The most reliable workflow is:

create a Neo4j database in Sandbox or Aura
run the Neo4j MCP server with your credentials
add that server to Claude Code
test with schema and count queries
expand to richer graph exploration and Cypher generation

That approach keeps setup simple and makes it easier to confirm each part works before moving on.

Quick answer

If you want the shortest version: create a Neo4j database, start a Neo4j MCP server with the database URI and credentials, add that server to Claude Code’s MCP configuration, restart Claude Code, and test it with a simple schema or Cypher query.

If you want, I can also give you a copy-paste Claude Code MCP config example for either Neo4j Aura, Neo4j Sandbox, or local Neo4j.