Neo4j Knowledge Graph MCP Server Guide

+-----------------------------------------------------------------------------------+
|                              Host Boundary                                        |
|                                                                                   |
|  +--------------------+        JSON-RPC 2.0 (stdio)        +-------------------+  |
|  |  Claude / Cursor   | <================================> |  neo4j-graph-mcp  |  |
|  +--------------------+                                    +---------+---------+  |
+----------------------------------------------------------------------|------------+
                                                                       | Bolt Protocol
                                                                       | (bolt://7687)
                                                                       v
                                                             +-------------------+
                                                             | Neo4j Aura / DBMS |
                                                             | (Nodes and Edges) |
                                                             +-------------------+

docker run -d --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/DevelopmentSecretPass123 \
  neo4j:5.25.0

curl -I 

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import neo4j from "neo4j-driver";

const uri = process.env.NEO4J_URI || "bolt://";
const user = process.env.NEO4J_USER || "neo4j";
const password = process.env.NEO4J_PASSWORD || "DevelopmentSecretPass123";

const driver = neo4j.driver(uri, neo4j.auth.basic(user, password));

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

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "read_cypher",
      description: "Execute a read-only Cypher query against the Neo4j database.",
      inputSchema: {
        type: "object",
        properties: {
          query: { type: "string", description: "The MATCH Cypher query to execute" },
          params: { type: "object", description: "Optional key-value query parameters", default: {} }
        },
        required: ["query"]
      }
    },
    {
      name: "get_schema",
      description: "Inspect active Node labels, Relationship types, and database property keys.",
      inputSchema: { type: "object", properties: {} }
    }
  ]
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (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.map(r => r.toObject()), null, 2) }]
      };
    } finally {
      await session.close();
    }
  }

  if (name === "read_cypher") {
    const { query, params = {} } = args as any;
    if (!query.trim().toUpperCase().startsWith("MATCH")) {
      throw new Error("Only read-only MATCH queries are permitted through this tool.");
    }
    const session = driver.session({ defaultAccessMode: neo4j.session.READ });
    try {
      const result = await session.run(query, params);
      const rows = result.records.map(r => r.toObject());
      return {
        content: [{ type: "text", text: JSON.stringify(rows, null, 2) }]
      };
    } finally {
      await session.close();
    }
  }

  throw new Error(`Tool not found: ${name}`);
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch(console.error);

{
  "mcpServers": {
    "neo4j": {
      "command": "node",
      "args": ["/absolute/path/to/neo4j-mcp/dist/index.js"],
      "env": {
        "NEO4J_URI": "bolt://",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "DevelopmentSecretPass123"
      }
    }
  }
}

{
  "mcpServers": {
    "neo4j": {
      "command": "node",
      "args": ["/absolute/path/to/neo4j-mcp/dist/index.js"],
      "env": {
        "NEO4J_URI": "bolt://",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "DevelopmentSecretPass123"
      }
    }
  }
}

[mcp_servers.neo4j]
command = "node"
args = ["/absolute/path/to/neo4j-mcp/dist/index.js"]
env = { NEO4J_URI = "bolt://", NEO4J_USER = "neo4j", NEO4J_PASSWORD = "DevelopmentSecretPass123" }

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "read_cypher",
    "arguments": {
      "query": "MATCH (s:Service)-[:DEPENDS_ON]->(target:Service {name: $targetName}) RETURN s.name AS dependentService LIMIT 10",
      "params": {
        "targetName": "AuthGateway"
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[\n  { \"dependentService\": \"OrderProcessingService\" },\n  { \"dependentService\": \"UserProfileService\" }\n]"
      }
    ],
    "isError": false
  }
}

CREATE CONSTRAINT service_name_unique FOR (s:Service) REQUIRE s.name IS UNIQUE;