Kuzu MCP Server for LLM Database Querying

Overview

The Kuzu MCP Server exposes Kuzu graph databases to large language models (LLMs) via the Model Context Protocol (MCP). It enables an LLM to inspect database schemas and execute Cypher-style queries against a provided Kuzu database instance. This is useful when you want an LLM to reason over structured graph data, generate queries from natural language, or fetch results for downstream tasks (summaries, dashboards, code generation).

The server is lightweight and designed to be embedded in LLM-enabled applications such as Claude Desktop or other MCP-capable clients. It supports both a Docker-based deployment (recommended for end users) and a Node.js-based mode for development, and it provides a read-only option to prevent accidental modifications.

Features

• Expose Kuzu database schema programmatically to LLMs
• Execute Cypher queries against a mounted Kuzu database file
• Prompt helper to convert natural-language questions into Kuzu-compatible Cypher
• Read-only mode to prevent write/DDL operations
• Easy integration with MCP-capable clients (for example Claude Desktop)
• Run via Docker for simple distribution or Node.js for local development

Installation / Configuration

Repository: https://github.com/kuzudb/kuzu-mcp-server

• Requirements:
  • Kuzu database file (.db) accessible on the host
  • Docker (recommended) or Node.js (for development)

Example Docker (recommended)

• Mount the directory containing your Kuzu database file and set KUZU_DB_FILE.

docker run --rm -i \
  -v /path/to/kuzu-db-dir:/database \
  -e KUZU_DB_FILE=kuzu.db \
  kuzudb/mcp-server

Example Docker with read-only mode

docker run --rm -i \
  -v /path/to/kuzu-db-dir:/database \
  -e KUZU_DB_FILE=kuzu.db \
  -e KUZU_READ_ONLY=true \
  kuzudb/mcp-server

Node.js (development)

• Install dependencies and run index.js directly passing the DB path:

# clone repository and install
git clone https://github.com/kuzudb/kuzu-mcp-server.git
cd kuzu-mcp-server
npm install

# start in dev mode (example)
node index.js /absolute/path/to/kuzu.db

Claude Desktop integration

• Edit the client config file to add an MCP server entry.

macOS:

• ~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

• %APPDATA%\Claude\claude_desktop_config.json

Example Docker entry for Claude config:

{
  "mcpServers": {
    "kuzu": {
      "command": "docker",
      "args": [
        "run",
        "-v",
        "/path/to/kuzu-db-dir:/database",
        "-e",
        "KUZU_DB_FILE=kuzu.db",
        "--rm",
        "-i",
        "kuzudb/mcp-server"
      ]
    }
  }
}

Example Node entry for Claude config:

{
  "mcpServers": {
    "kuzu": {
      "command": "node",
      "args": [
        "/absolute/path/to/kuzu-mcp-server/index.js",
        "/absolute/path/to/kuzu.db"
      ]
    }
  }
}

Available Tools

The server exposes a small set of MCP tools and a prompt helper that LLMs can use.

Usage pattern:

1. Call getSchema to understand available labels, relationships, and properties.
2. Use generateKuzuCypher (or directly craft) to build a Cypher query.
3. Submit the query via the query tool and inspect results.

Use Cases

• Schema exploration
  • Ask the server via getSchema to list node and relationship tables, then use that for context-aware query generation.
• Natural-language to Cypher conversion
  • Prompt the LLM to convert: “Find top 5 users by number of purchases in 2023” → generateKuzuCypher produces a Cypher string you can run with query.
• Safe read-only analytics
  • Mount your production DB in read-only mode (KUZU_READ_ONLY=true) so LLMs can run SELECT-style queries but writes and schema changes are blocked.
• Interactive data debugging in an LLM-enabled environment
  • Combine schema introspection and ad-hoc queries to have the model explain data shapes and produce SQL/Cypher snippets for reports.
• App integration
  • Use the Docker server as a backend MCP endpoint for desktop or web clients that expose data-aware LLM features.

Example Cypher (run via query tool)

MATCH (u:User)-[p:PURCHASED]->(i:Item)
RETURN u.user_id AS userId, count(p) AS purchases
ORDER BY purchases DESC
LIMIT 10;

Notes and best practices

• Always call getSchema first so the LLM can target correct labels and properties.
• Enable KUZU_READ_ONLY in production when you only need analytics to protect your dataset.
• Validate generated Cypher before executing if untrusted models are used (defensive filtering for writes/DDL).

For full details, examples and updates see the repository: https://github.com/kuzudb/kuzu-mcp-server.