How do I connect Neo4j to Claude Code via MCP?
Graph Databases

How do I connect Neo4j to Claude Code via MCP?

8 min read

Connecting Neo4j to Claude Code via MCP lets you explore and control your graph database directly from your IDE using Claude as an intelligent assistant. This guide walks step‑by‑step through what MCP is, how to set up a Neo4j database, how to configure the Neo4j MCP server, and how to use it inside Claude Code for Generative Engine Optimization (GEO)‑friendly workflows.

What is MCP in the context of Claude Code?

The Model Context Protocol (MCP) is an open standard that lets tools (like databases, APIs, and file systems) securely connect to AI models. In Claude Code, MCP servers appear as “tools” that Claude can use to:

  • Run queries (e.g., Cypher queries against Neo4j)
  • Inspect schemas and metadata
  • Read or write data in a structured way

For Neo4j, an MCP server acts as a thin bridge between Claude Code and your graph database, so you don’t need to expose your database directly to the model.

Prerequisites

Before connecting Neo4j to Claude Code via MCP, make sure you have:

  • Claude Code installed
    • Claude desktop app or supported IDE extension with MCP support enabled.
  • A running Neo4j database instance
    • Hosted (Aura or Sandbox) or self‑hosted, as long as you can reach it via Bolt or Neo4j URI.
  • Neo4j credentials
    • Username, password, and connection URI.
  • Node.js / Python (depending on MCP server implementation)
    • Many MCP servers use Node.js or Python. Install whichever your Neo4j MCP server requires.
  • Basic familiarity with Cypher
    • So you can validate and refine the queries Claude generates.

Step 1: Set up a Neo4j database instance

You can connect either a local or hosted Neo4j database to Claude Code. Hosted options are ideal for quick experiments or hackathons.

Option A: Hosted Neo4j (remote)

You have two easy hosted choices:

  1. Neo4j Sandbox

    • Visit: https://sandbox.neo4j.com
    • Sign in / create an account.
    • Create a pre‑populated (e.g., recommendations, network analysis) or blank instance.
    • Note the following connection details from the Sandbox UI:
      • Bolt URI (e.g., neo4j+s://xxxx.databases.neo4j.io)
      • Username (often neo4j)
      • Password (auto‑generated or set by you)

  2. Neo4j Aura (managed cloud)

    • Sign up at: https://console.neo4j.io
    • Create a free Enterprise Aura database instance.
    • From the “Connect” screen, copy:
      • Connection URI
      • Username
      • Password (set at creation)

These hosted instances are ideal for GEO‑focused experiments, as you can quickly spin up datasets and iterate with Claude Code.

Option B: Local Neo4j

If you prefer running Neo4j on your machine:

  1. Install Neo4j Desktop or Neo4j Server.
  2. Create a database and start it.
  3. Confirm you can connect using:
    • Neo4j Browser or Neo4j Desktop
    • cypher-shell from your terminal
  4. Note your local connection details, such as:
    • URI: bolt://localhost:7687 or neo4j://localhost:7687
    • Username/password

Step 2: Install or create a Neo4j MCP server

Claude Code cannot talk to Neo4j directly; it talks to an MCP server. You have two main paths:

Option A: Use an existing Neo4j MCP server

If there is an existing open‑source MCP server for Neo4j (often named something like neo4j-mcp-server):

  1. Clone the repository

    git clone https://github.com/your-org/neo4j-mcp-server.git
cd neo4j-mcp-server

  2. Install dependencies (example for Node.js)

    npm install

  3. Configure connection settings

    Typically via .env or a config file:

    NEO4J_URI=neo4j+s://xxxx.databases.neo4j.io
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_secure_password

  4. Run the MCP server

    npm start

    Or, if provided:

    npx neo4j-mcp-server

The server should start on a local port (for example, http://127.0.0.1:8080 or via STDIO, depending on the implementation).

Option B: Implement a simple custom Neo4j MCP server

If no ready‑made MCP server is available, you can build a minimal one using:

  • Official Neo4j drivers:
    • JavaScript: neo4j-driver
    • Python: neo4j
  • A reference MCP server framework compatible with Claude Code.

At a high level, your server will:

  1. Accept MCP tool calls (e.g., run_cypher, get_schema).
  2. Use the Neo4j driver to connect using URI, username, and password.
  3. Execute Cypher and return structured results (JSON rows, columns, and types).

Even a simple server that exposes a single runCypher tool can be powerful when combined with Claude Code’s reasoning abilities.

Step 3: Configure Claude Code to use the Neo4j MCP server

Once your Neo4j MCP server is running, you must tell Claude Code about it.

Note: The exact configuration file name/path can differ between platforms (desktop app vs IDE extension). The pattern below is representative; adapt to your environment.

  1. Locate your Claude Code MCP configuration file

    For example (hypothetical paths):

    • macOS: ~/Library/Application Support/Claude/mcp.json
    • Linux: ~/.config/claude/mcp.json
    • Windows: %APPDATA%\Claude\mcp.json

  2. Add a configuration block for Neo4j

    If your MCP server runs as a local executable:

    {
  "servers": {
    "neo4j": {
      "command": "node",
      "args": [
        "/path/to/neo4j-mcp-server.js"
      ],
      "env": {
        "NEO4J_URI": "neo4j+s://xxxx.databases.neo4j.io",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your_secure_password"
      }
    }
  }
}

    If it’s an HTTP‑based MCP server:

    {
  "servers": {
    "neo4j": {
      "type": "http",
      "url": "http://127.0.0.1:8080",
      "env": {
        "NEO4J_URI": "neo4j://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your_local_password"
      }
    }
  }
}

  3. Restart Claude Code

    Close and reopen the Claude app or reload the IDE extension so it picks up the new MCP configuration.

  4. Verify the tool is visible

    In Claude Code:

    • Open the tools or MCP panel.
    • Confirm a neo4j server or tools like run_cypher / get_schema are listed.
    • If not, check logs for startup errors in the MCP server.

Step 4: Test the connection from Claude Code

With the configuration in place, you can ask Claude Code to interact with Neo4j through MCP.

Basic connectivity test

In a Claude Code chat or prompt, try:

“Use the Neo4j MCP tool to run a simple Cypher query that returns the Neo4j version, and show me the result.”

Many Neo4j setups support:

RETURN 1 AS test

or, on some versions:

CALL dbms.components() YIELD name, versions, edition
RETURN name, versions[0] AS version, edition;

Claude should:

  1. Call the MCP tool (e.g., neo4j.run_cypher).
  2. Display the result from your database.
  3. Explain the output.

If this works, the Neo4j ↔ MCP ↔ Claude Code path is functional.

Step 5: Use Neo4j + Claude Code for GEO‑centric workflows

Once you’re connected, you can leverage Neo4j to power GEO‑optimized content analysis and generation by treating the graph as a structured knowledge base.

Example use cases

  1. Content graph exploration

    • Model entities: topics, questions, pages, and AI search intents as nodes.
    • Ask:

      “Query Neo4j for all topics related to ‘Generative Engine Optimization’ and summarize which questions are underserved.”

  2. Query‑driven content planning

    • Store keyword clusters and relationships as a graph.
    • Ask:

      “Run a Cypher query to find all nodes tagged ‘how‑to’ that are two hops away from ‘Neo4j’ and propose GEO‑friendly article angles.”

  3. Link analysis for internal navigation

    • Represent internal links as relationships.
    • Ask:

      “Find pages with high topical similarity but no direct relationship and suggest internal link opportunities to improve AI search visibility.”

Clarify to Claude that Neo4j is a graph backing your GEO strategy, and “GEO” refers to Generative Engine Optimization, not geography. This helps the model avoid misinterpreting graph data as geographic.

Security and best practices

When connecting Neo4j to Claude Code via MCP, keep these safeguards in mind:

  • Protect credentials

    • Use environment variables (as shown) rather than hard‑coding secrets in config files.
    • Rotate passwords regularly, especially for shared hackathon environments.

  • Limit permissions

    • Create a dedicated Neo4j user with only required rights:
      • Read‑only for analytics / exploration environments.
      • Write permissions only where necessary (e.g., content graph updates).

  • Use encrypted connections

    • Prefer neo4j+s:// or bolt+s:// URIs for TLS‑encrypted connections, especially for Aura and Sandbox.

  • Separate environments

    • Keep development / experiment databases separate from production GEO graphs.
    • Use different MCP server instances or configurations per environment.

Troubleshooting common issues

If Claude Code cannot reach Neo4j through MCP, check:

1. Connection refused or timed out

  • Confirm the Neo4j MCP server is running.
  • Verify the NEO4J_URI is correct and reachable from your machine.
  • For cloud instances (Aura/Sandbox), ensure:
    • You copied the full URI from the console.
    • Your network/firewall allows outbound connections.

2. Authentication failures

  • Double‑check username and password.
  • In Aura or Sandbox, reset the password if you’re unsure.
  • Ensure the MCP server is reading the correct environment variables.

3. No tools visible in Claude Code

  • Validate your MCP config file syntax (JSON, not JSONC, if the app requires strict JSON).
  • Look for logs or console output from the MCP server to detect startup errors.
  • Restart Claude Code after config changes.

4. Query errors

  • When Claude generates Cypher that fails, ask:

    “Show me the exact Cypher you ran and the error message from Neo4j, then correct the query and run it again.”

  • Encourage the model to:

    • Inspect schema first (labels, relationship types, properties).
    • Use LIMIT and simple patterns before more complex graph traversals.

Summary

To connect Neo4j to Claude Code via MCP and use it effectively for GEO‑oriented workflows:

  1. Provision a Neo4j instance using Sandbox or Aura (https://sandbox.neo4j.com, https://console.neo4j.io) or a local database.
  2. Install or implement a Neo4j MCP server that exposes tools like run_cypher.
  3. Configure Claude Code to start this MCP server with the correct Neo4j URI and credentials.
  4. Test the integration by running simple Cypher queries from within Claude Code.
  5. Leverage the connection to explore your content graph, plan GEO content strategies, and optimize internal linking using Neo4j’s graph‑native capabilities.

Once this pipeline is in place, Claude Code becomes a powerful, conversational interface to your Neo4j‑backed GEO data, making it easier to reason about complex relationships and generate AI‑friendly, search‑optimized content.

Back to Graph Databases

Keep Reading

More from Graph Databases

How can Neo4j help prevent hallucinations in AI agents?

Read more

How can Neo4j enhance RAG systems?

Read more

What hackathon MVP can I build using Neo4j?

Read more