Kuzu MCP Server

What is Kuzu MCP Server about?

Enables large language models to retrieve the full schema of a Kuzu graph database and run Cypher queries against it. The server follows the Model Context Protocol, exposing tools and prompts that agents can call to interact with the underlying database.

How to use Kuzu MCP Server?

Docker (recommended)

1. Place your Kuzu database file in a directory on the host.
2. Edit Claude Desktop’s config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\\Claude\\claude_desktop_config.json).
3. Add a kuzu entry under mcpServers:

{
  "mcpServers": {
    "kuzu": {
      "command": "docker",
      "args": [
        "run",
        "-v",
        "{HOST_DIR}:/database",
        "-e",
        "KUZU_DB_FILE={DB_FILENAME}",
        "--rm",
        "-i",
        "kuzudb/mcp-server"
      ]
    }
  }
}

Replace {HOST_DIR} with the absolute path to the directory containing the database and {DB_FILENAME} with the file name. 4. Restart Claude Desktop; the server will be available under the name kuzu.

Node.js (development)

1. Clone the repository and run npm install.
2. Add a kuzu entry to config.json:

{
  "mcpServers": {
    "kuzu": {
      "command": "node",
      "args": [
        "{ABS_PATH_TO_REPO}/index.js",
        "{ABS_PATH_TO_DB_FILE}"
      ]
    }
  }
}

3. Restart Claude Desktop.

Read‑Only Mode

Set the environment variable KUZU_READ_ONLY=true in the Docker or Node configuration to prevent any mutating queries.

Key Features

• getSchema tool – Returns the complete Kuzu schema, including node and relationship tables with their properties.
• query tool – Executes arbitrary Cypher statements and returns results.
• generateKuzuCypher prompt – Helps LLMs translate natural‑language questions into Cypher queries.
• Read‑only mode – Optional safety mode that blocks write operations.
• Docker image – Pre‑built kuzudb/mcp-server for quick deployment.

Use Cases

• Building autonomous agents that explore and analyze graph data stored in Kuzu.
• Enabling chatbot assistants to answer domain‑specific questions by querying a Kuzu knowledge graph.
• Providing a sandboxed, read‑only view of a production graph for auditing or reporting.
• Rapid prototyping of LLM‑driven data pipelines that need schema awareness.

FAQ

Q: Which environment variable points to the database file? A: KUZU_DB_FILE should contain the filename of the Kuzu database located in the mounted /database directory.

Q: How do I enable read‑only mode? A: Add -e "KUZU_READ_ONLY=true" to the Docker args or set KUZU_READ_ONLY=true in the Node environment.

Q: Can I run multiple Kuzu instances simultaneously? A: Yes, define separate entries under mcpServers with different names and distinct mount paths.

Q: What response format does the query tool return? A: Standard MCP JSON containing column names and row data, mirroring typical Cypher result sets.

Q: Do I need to build the Docker image myself? A: No, the official image kuzudb/mcp-server is published on Docker Hub and can be pulled automatically.

kuzu-mcp-server

A Model Context Protocol server that provides access to Kuzu databases. This server enables LLMs to inspect database schemas and execute queries on provided kuzu database.

Components

Tools

• getSchema

  • Fetch the full schema of the Kuzu database, including all nodes and relationships tables and their properties
  • Input: None

• query

  • Run a Cypher query on the Kuzu database
  • Input: cypher (string): The Cypher query to run

Prompt

• generateKuzuCypher
  • Generate a Cypher query for Kuzu
  • Argument: question (string): The question in natural language to generate the Cypher query for

Usage with Claude Desktop

With Docker (Recommended)

• Edit the configuration file config.json:
  • on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • on Windows: %APPDATA%\Claude\claude_desktop_config.json
• Add the following configuration to the mcpServers object:

  {
    "mcpServers": {
        "kuzu": {
            "command": "docker",
            "args": [
                "run",
                "-v",
                "{Path to the directory containing Kuzu database file}:/database",
                "-e",
                "KUZU_DB_FILE={Kuzu database file name}",
                "--rm",
                "-i",
                "kuzudb/mcp-server"
            ]
        }
    }
  }
  

  Change the {Path to the directory containing Kuzu database file} to the actual path
• Restart Claude Desktop

With Node.js and npm (for Development)

• Install dependencies: npm install
• Edit the configuration file config.json:
  • on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • on Windows: %APPDATA%\Claude\claude_desktop_config.json
• Add the following configuration to the mcpServers object:

  {
    "mcpServers": {
        "kuzu": {
            "command": "node",
            "args": [
                "{Absolute Path to this repository}/index.js",
                "{Absolute Path to the Kuzu database file}",
            ]
        }
    }
  }
  

  Change the {Absolute Path to this repository} and {Absolute Path to the Kuzu database file} to the actual paths
• Restart Claude Desktop

Read-Only Mode

The server can be run in read-only mode by setting the KUZU_READ_ONLY environment variable to true. In this mode, running any query that attempts to modify the database will result in an error. This flag can be set in the configuration file as follows:

{
    "mcpServers": {
        "kuzu": {
            "command": "docker",
            "args": [
                "run",
                "-v",
                "{Path to the directory containing Kuzu database file}:/database",
                "-e",
                "KUZU_DB_FILE={Kuzu database file name}",
                "-e",
                "KUZU_READ_ONLY=true",
                "--rm",
                "-i",
                "kuzudb/mcp-server"
            ],
        }
    }
}