Kuzu MCP Server

Kuzu MCP Server

What is Kuzu MCP Server about?

Kuzu MCP Server exposes a Model Context Protocol interface for Kuzu databases. It lets large language models (LLMs) inspect the full database schema—nodes, relationships, and their properties—and execute arbitrary Cypher queries.

How to use Kuzu MCP Server?

1. Docker (recommended) – Add a configuration entry to Claude Desktop’s config.json pointing to a Docker run command that mounts the directory containing the .kuzu file and sets the KUZU_DB_FILE environment variable.
2. Node.js / npm (development) – Install the repository’s npm dependencies, then configure Claude Desktop to launch the server with Node, passing the absolute path to index.js and the database file.
3. Read‑only mode – Set the KUZU_READ_ONLY=true environment variable in the configuration to prevent any write operations.

Key features of Kuzu MCP Server

• Schema retrieval – getSchema tool returns a complete description of all node and relationship tables.
• Cypher execution – query tool runs any Cypher statement and returns results.
• Prompt generation – generateKuzuCypher prompt helps LLMs translate natural‑language questions into Cypher queries.
• Docker‑first deployment – Simple, isolated container execution.
• Optional read‑only mode – Safe for environments where mutations are disallowed.

Use cases of Kuzu MCP Server

• LLM‑driven data exploration – Let an assistant browse a graph database without hard‑coding queries.
• Chat‑based analytics – Users ask natural‑language questions and receive answers derived from Cypher queries.
• Application prototyping – Rapidly test how LLMs interact with a Kuzu schema before building full integrations.
• Secure query sandbox – Deploy in read‑only mode to expose data without risking modifications.

FAQ from the Kuzu MCP Server

• Do I need to build the Docker image? No. The image kuzudb/mcp-server is published publicly and can be pulled automatically.
• Can I run multiple databases simultaneously? Yes, launch separate server instances with different mount paths and KUZU_DB_FILE values.
• What happens if I send a write query in read‑only mode? The server returns an error indicating that the operation is not permitted.
• Is authentication supported? Not out‑of‑the‑box; you would need to wrap the server with your own auth layer.
• How do I update the server? Pull the latest Docker image or git pull the repository and reinstall npm dependencies.

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"
            ],
        }
    }
}