Neo4j GraphRAG MCP Server: Unlock Knowledge Graphs in Claude Desktop

By Deepak Bagada, CEO at SaaSNext & Principal AI Architect

As AI agents move beyond simple document retrieval, Graph Retrieval-Augmented Generation (GraphRAG) has become the gold standard for enterprise reasoning. The Neo4j GraphRAG MCP Server bridges the gap between your local AI workflows in Cursor or Claude Desktop and powerful graph databases. This MCP tool enables AI to traverse complex relationships, query Cypher natively, and extract deep contextual insights that traditional vector databases miss.

Why GraphRAG over Standard Vector Search?

Standard vector databases are excellent for semantic similarity, but they struggle with multi-hop reasoning. If you ask an AI, "Which engineers contributed to projects led by Sarah that use React?", a vector database might return documents mentioning Sarah and React, but fail to connect the exact engineers. A Neo4j graph database, accessed via this MCP server, traverses the relationships (ENGINEER -> CONTRIBUTED_TO -> PROJECT <- LED_BY <- MANAGER) to provide a precise, deterministic answer.

With the Neo4j MCP Server, your LLM can dynamically generate Cypher queries, execute them securely, and visualize the returned subgraphs—all within your MCP ecosystem.

In addition to overcoming the limitations of standard cosine similarity searches, GraphRAG provides explicit provenance. When the AI makes a claim, it can trace that claim back to specific nodes and edges in the graph. This explainability is absolutely critical in domains like healthcare, finance, and legal tech, where hallucinations are unacceptable.

Deep Dive: Core Capabilities & Features

The Neo4j MCP Server is not just a simple query runner; it's a comprehensive interface designed specifically for autonomous AI agents.

- **Dynamic Cypher Execution:** Safely execute read-only or transactional Cypher queries with parameterized inputs. The server automatically handles connection pooling and session management.
- **Schema Introspection & Discovery:** Before writing a query, the LLM can use the `get_schema` tool to automatically discover node labels, relationship types, and property keys. This drastically reduces syntax errors and hallucinated queries.
- **GraphRAG Hybrid Search:** Combine full-text search, vector embeddings, and graph traversals in a single tool call. The MCP server integrates with Neo4j's native vector index to perform hybrid retrieval seamlessly.
- **OAuth 2.0 & Role-Based Access:** Secure enterprise deployments with robust authentication mechanisms. Integrate with your corporate SSO to ensure the AI only sees what the human user is authorized to see.
- **Interactive Data Visualization:** When integrated with tools like Claude Desktop, the server can format responses in Markdown tables or even Mermaid.js diagrams to visually represent the retrieved subgraph.

Real-World Use Cases

How are top engineering teams using the Neo4j MCP Server today?

1. Supply Chain & Logistics Optimization

Supply chains are inherently graphs. Using this MCP server, an AI assistant can analyze a disruption in a manufacturing plant, traverse the graph to find all dependent products, identify alternate suppliers, and draft an impact report in seconds. The AI writes the Cypher query, processes the nested JSON results, and synthesizes the final report.

2. Codebase Architecture Mapping

Imagine dumping your entire microservices architecture into Neo4j. The AI can then use the MCP server to answer questions like, "Which services will be affected if I change this specific API endpoint in the authentication service?" The graph reveals the exact call paths, allowing the AI to write more accurate code modifications.

3. Fraud Detection & KYC

Financial institutions use GraphRAG to detect circular money flows and synthetic identities. The AI agent can be tasked with investigating a suspicious entity, using the MCP tool to pull immediate connections and flag anomalous patterns that standard tabular queries would miss.

Installation and Setup Guide

To integrate the Neo4j GraphRAG MCP Server into your environment, you need to configure your client. Add the following configuration to your claude_desktop_config.json or Cursor settings:

{
  "mcpServers": {
    "neo4j-graphrag": {
      "command": "npx",
      "args": ["-y", "@neo4j/mcp-server-graphrag"],
      "env": {
        "NEO4J_URI": "neo4j+s://your-instance.databases.neo4j.io",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your-secure-password",
        "NEO4J_MAX_CONNECTION_POOL_SIZE": "50"
      }
    }
  }
}

Once configured, restart your AI client. The AI will immediately recognize the new tools and can begin querying the database.

Core Input Schema (Zod/JSON) Definition

The server exposes several tools. The primary tool, execute_cypher, uses the following strict input schema to ensure precise and safe query execution. By defining parameters explicitly, the MCP server prevents Cypher injection attacks.

{
  "name": "execute_cypher",
  "description": "Executes a Cypher query against the Neo4j database to retrieve graph data. Use get_schema first to understand the data model.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "The Cypher query to execute. Must be read-only unless write permissions are explicitly granted."
      },
      "parameters": {
        "type": "object",
        "description": "JSON object containing query parameters to prevent Cypher injection. Keys must match parameter names in the query."
      },
      "database": {
        "type": "string",
        "description": "Optional. The specific database to query within the Neo4j DBMS."
      }
    },
    "required": ["query"]
  }
}

Enterprise Security: OAuth 2.0 & RBAC Guide

For enterprise environments, hardcoding passwords in the MCP configuration is a major security risk. The Neo4j MCP Server supports advanced OAuth 2.0 authentication via Entra ID, Okta, or Keycloak.

To configure OAuth 2.0 securely:

- Register a new confidential client application in your Identity Provider (IdP) and obtain a `CLIENT_ID` and `CLIENT_SECRET`.
- Configure your Neo4j Aura instance or self-hosted cluster to use the IdP as an OIDC provider. Ensure claims mapping is set up to map JWT roles to Neo4j native roles.
- Update the MCP environment variables to use a dynamically generated `NEO4J_AUTH_TOKEN`. This can be achieved by writing a small shell script wrapper that fetches the token before starting the node process, or configuring the server to run an OAuth device authorization flow on startup.

Always enforce least-privilege access. Ensure the AI's database user is restricted to a read-only role (e.g., db_reader) unless specific write operations are explicitly required for your automated workflows. Never grant the AI admin privileges on a production cluster.

TypeScript Implementation Blueprint

If you wish to build a custom wrapper or extend the official server with proprietary business logic, here is a comprehensive TypeScript implementation using the official Model Context Protocol SDK:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import neo4j from "neo4j-driver";
import { z } from "zod";

const driver = neo4j.driver(
  process.env.NEO4J_URI!,
  neo4j.auth.basic(process.env.NEO4J_USERNAME!, process.env.NEO4J_PASSWORD!),
  { maxConnectionPoolSize: 50 }
);

const server = new Server(
  { name: "neo4j-mcp-enterprise", version: "2.1.0" },
  { capabilities: { tools: {} } }
);

// Define tool schemas
server.setRequestHandler("ListToolsRequest", async () => ({
  tools: [
    {
      name: "execute_cypher",
      description: "Run a Cypher query against the knowledge graph",
      inputSchema: {
        type: "object",
        properties: {
          query: { type: "string" },
          params: { type: "object" }
        },
        required: ["query"]
      }
    },
    {
      name: "get_schema",
      description: "Retrieve the current graph schema",
      inputSchema: {
        type: "object",
        properties: {}
      }
    }
  ]
}));

// Handle tool execution
server.setRequestHandler("CallToolRequest", async (request) => {
  if (request.params.name === "get_schema") {
     const session = driver.session({ defaultAccessMode: neo4j.session.READ });
     try {
       const result = await session.run("CALL db.schema.visualization()");
       return { content: [{ type: "text", text: JSON.stringify(result.records) }] };
     } finally {
       await session.close();
     }
  }

  if (request.params.name === "execute_cypher") {
    const session = driver.session({ defaultAccessMode: neo4j.session.READ });
    try {
      const result = await session.run(
        request.params.arguments.query as string,
        request.params.arguments.params as any || {}
      );
      // Format results for the LLM
      const formatted = result.records.map(record => record.toObject());
      return {
        content: [{ type: "text", text: JSON.stringify(formatted, null, 2) }]
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: `Database Error: ${error.message}` }],
        isError: true
      };
    } finally {
      await session.close();
    }
  }
  throw new Error("Tool not found");
});

const transport = new StdioServerTransport();
server.connect(transport).catch(console.error);

Unlocking Advanced AI Reasoning

By connecting Claude or Cursor to your Neo4j graph, you empower your AI to perform complex supply chain analysis, fraud detection, and multi-document synthesis natively. The AI can dynamically explore relationships, mapping out entire knowledge domains in real time. This represents a monumental shift from simple keyword-based RAG to true agentic knowledge workers.

As AI agents become more autonomous, their ability to reason over structured graph data will be the defining factor in their utility. The Neo4j MCP Server is the crucial bridge that makes this possible.

To explore more tools that enhance your AI's capabilities and build the ultimate autonomous stack, check out our comprehensive MCP Directory.

FAQs

What is GraphRAG?

GraphRAG (Graph Retrieval-Augmented Generation) uses graph databases to retrieve highly structured, interconnected data, allowing LLMs to answer complex relational questions more accurately than vector-only RAG. It significantly reduces hallucinations by grounding the AI in explicit relationships.

Can the Neo4j MCP Server write data to the database?

Yes, but it depends entirely on the permissions granted to the database user configured in the MCP environment variables. We strongly recommend using read-only credentials (like the db_reader role) for general AI tasks to prevent accidental data modification.

Is this tool compatible with Cursor and other IDEs?

Absolutely. Any IDE or platform that supports the Model Context Protocol, including Cursor, Claude Desktop, and emerging AI agent frameworks, can utilize this server seamlessly. The protocol is standard across the industry.