The Model Context Protocol (MCP) is revolutionizing how we connect LLMs to our data sources. If you’ve been working with knowledge graphs and LLMs, you probably know how powerful it is to give AI the ability to directly query and inspect graph databases.

Neo4j MCP Claude Integration

In this article, I’ll walk you through an end-to-end guide to run a local Neo4j instance, populate it with sample data, and connect it to Claude Code in two ways:

  1. Directly via the official Neo4j MCP server.
  2. Wrapped in a Claude Code skill that adds a procedural layer for schema inspection, error recovery, and result ranking.

We’ll also cover MCPorter — a CLI that proxies MCP calls as plain shell commands — for token-sensitive setups and use outside of Claude.

Repository

The complete source code and configuration for this tutorial is available on GitHub:

https://github.com/GaetanoPiazzolla/neo4j-mcp

1. Start Neo4j

First, we need to spin up a local Neo4j instance using Docker.

docker compose up -d

Verify the server is running by navigating to http://localhost:7474.

Field Value
User neo4j
Password neo4jneo4j

To stop the container later, you can simply run docker compose down.

2. Populate the Database

An empty graph database isn’t much fun to query. My import script creates the target database and loads the classic Northwind dataset (products, categories, suppliers, customers, orders).

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python run_import.py

Expected output:

Database 'mcp-test' ready.
Connected. Running 14 statement(s) from northwind.cypher
...
Import complete.

(Note: The script is idempotent, so you can run it multiple times safely.)

3. Install the neo4j-mcp Binary

Next, download the neo4j-mcp binary for your platform from the official releases page.

macOS (Apple Silicon):

curl -L https://github.com/neo4j/mcp/releases/latest/download/neo4j-mcp_Darwin_arm64.tar.gz | tar xz neo4j-mcp
sudo mv neo4j-mcp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/neo4j/mcp/releases/latest/download/neo4j-mcp_Darwin_x86_64.tar.gz | tar xz neo4j-mcp
sudo mv neo4j-mcp /usr/local/bin/

Linux (amd64):

curl -L https://github.com/neo4j/mcp/releases/latest/download/neo4j-mcp_Linux_x86_64.tar.gz | tar xz neo4j-mcp
sudo mv neo4j-mcp /usr/local/bin/

Verify the installation:

neo4j-mcp -v

4. Register neo4j-mcp in Claude Code

Now for the magic part: adding the MCP server to Claude Code so the LLM can query our graph.

claude mcp add \
      --transport stdio \
      -e NEO4J_URI=bolt://127.0.0.1:7687 \
      -e NEO4J_USERNAME=neo4j \
      -e NEO4J_PASSWORD=neo4jneo4j \
      -e NEO4J_DATABASE=neo4j \
      -e NEO4J_READ_ONLY=true \
      -- neo4j-mcp neo4j-mcp

Verify that the MCP was added correctly:

claude mcp list

Claude Code now has three powerful tools available against your local database:

  • get-schema: Inspect labels, relationship types, and properties.
  • read-cypher: Run read-only Cypher queries.
  • write-cypher: Run write queries.

Try asking Claude Code questions like:

  • What products are currently in stock?
  • Which customers have placed the most orders?
  • What are the top 5 most expensive products?
  • Which suppliers provide beverages?

The Power of Claude Code Skills

The MCP server gives Claude the tools. A skill gives it the judgment to use them well.

A skill is a markdown file loaded on-demand into Claude’s context when invoked. It sits above the raw MCP layer and encodes decisions that the model would otherwise have to infer: inspect the schema before writing Cypher, retry with a reformulated query before surfacing an error, or re-rank results by relevance rather than returning whatever the query happened to return. The LLM runs that logic natively between tool calls, chaining schema inspection, querying, and summarization within a single turn.

You can find the sample skill in my repo at .claude/skills/neo4j-query/SKILL.md. It directly calls the registered MCP tools:

mcp__neo4j-mcp__get-schema
mcp__neo4j-mcp__read-cypher  { query: "<CYPHER>" }

What is MCPorter?

MCPorter is a Node.js CLI that proxies calls to any MCP server as plain shell commands — useful for scripting, CI, or calling MCP tools from outside Claude entirely.

When neo4j-mcp is registered in Claude Code natively, its full tool schema loads into every conversation, including ones that never touch the database. For large schemas or setups where every token counts, that overhead is constant and unavoidable.

A skill backed by MCPorter trades that for on-demand loading: the markdown enters context only when the skill is invoked, and the MCP registration can be removed entirely.

Install it globally:

npm install -g mcporter

Configure MCPorter

Create a configuration file at ~/.mcporter/mcporter.json:

{
  "mcpServers": {
    "neo4j-mcp": {
      "command": "neo4j-mcp",
      "env": {
        "NEO4J_URI": "${NEO4J_URI}",
        "NEO4J_USERNAME": "${NEO4J_USERNAME}",
        "NEO4J_PASSWORD": "${NEO4J_PASSWORD}",
        "NEO4J_DATABASE": "${NEO4J_DATABASE:-neo4j}",
        "NEO4J_READ_ONLY": "${NEO4J_READ_ONLY:-true}"
      }
    }
  }
}

Load your .env file credentials and test it out via function-call syntax:

export $(grep -v '^#' .env | xargs)
mcporter call 'neo4j-mcp.read-cypher(query: "MATCH (p:Product) RETURN p.productName LIMIT 5")'

The CLI-Variant Skill

You can create a Claude Code skill that leverages this CLI setup, exporting credentials and executing mcporter via the Bash tool. You’ll find an example of this in the repo at .claude/skills/neo4j-query-cli/SKILL.md.

Conclusion: MCP, CLI, or both?

For most use cases, adding the MCPorter path introduces complexity without much payoff. Registering the MCP server directly allows the model to reason natively between tool calls and effortlessly perform error recovery. The token overhead from the MCP server schema is real, but for local development and experimentation, it rarely matters.

However, MCPorter shines in two specific scenarios:

  1. Token-sensitive setups where loading the schema on every conversational turn is genuinely costly.
  2. Scripting and CI/CD, where its value has nothing to do with Claude at all. Once configured, any terminal or script can invoke Neo4j through the exact same MCP interface.
Approach When it makes sense
Native MCP + Skill Default. Simplest setup, full LLM reasoning, no extra tooling.
MCP removed + MCPorter CLI Skill Token-sensitive setups where schema overhead matters.
MCPorter standalone Scripting, CI, or calling MCP tools from outside Claude entirely.

Integrating graph databases with AI agents unlocks an entirely new layer of context and accuracy for your LLMs. Give this setup a try, and let me know how you leverage the Neo4j MCP in your workflows!