kuzudb-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.

Quick Start

For quick testing and development:

# Install the package
npm install -g kuzudb-mcp-server
# or use pnpm/yarn

# Clone the repository for development
git clone https://github.com/jordanburke/kuzudb-mcp-server.git
cd kuzudb-mcp-server
pnpm install

# Quick test with auto-created database
pnpm serve:test              # stdio transport (default)
pnpm serve:test:http         # HTTP transport
pnpm serve:test:inspect      # HTTP with MCP Inspector

# Initialize databases manually
pnpm db:init                 # Create empty test database
pnpm db:init:movies          # Create database with movie data

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",
                "{Absolute Path to the Kuzu database}:/database",
                "--rm",
                "-i",
                "kuzudb/mcp-server"
            ]
        }
    }
  }
  

  Change the {Absolute Path to the Kuzu database} to the actual path
• Restart Claude Desktop

With npm/npx

• Install globally: npm install -g kuzudb-mcp-server
• Or use directly with npx: npx kuzudb-mcp-server
• 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": "npx",
            "args": [
                "kuzudb-mcp-server",
                "{Absolute Path to the Kuzu database}"
            ]
        }
    }
  }
  

  Change the {Absolute Path to the Kuzu database} to the actual path
• Restart Claude Desktop

With Smithery

This server is available on Smithery for easy installation:

# Install via Smithery CLI
smithery install kuzudb-mcp-server

# The server auto-initializes with a sample movies database
# No manual database setup required!

The Smithery version includes:

• Automatic database initialization with movies template
• No volume mounting required
• Ready-to-use graph database for testing and exploration

Using Environment Variables

You can also specify the database path using the KUZU_MCP_DATABASE_PATH environment variable instead of passing it as an argument:

{
    "mcpServers": {
        "kuzu": {
            "command": "npx",
            "args": ["kuzudb-mcp-server"],
            "env": {
                "KUZU_MCP_DATABASE_PATH": "{Absolute Path to the Kuzu database}"
            }
        }
    }
}

Alternatively, if you have KUZU_MCP_DATABASE_PATH set in your system environment, the server will automatically use it when no database path argument is provided.

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:

With npm/npx:

{
    "mcpServers": {
        "kuzu": {
            "command": "npx",
            "args": [
                "kuzudb-mcp-server",
                "{Absolute Path to the Kuzu database}"
            ],
            "env": {
                "KUZU_READ_ONLY": "true"
            }
        }
    }
}

With Docker:

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

Remote Connection (HTTP Transport)

The server supports both stdio (default) and HTTP transports, allowing remote connections and easier debugging.

Docker Deployment (HTTP Server)

The easiest way to run the HTTP server is using Docker. Pre-built images are available from GitHub Container Registry:

# Pull the latest image
docker pull ghcr.io/jordanburke/kuzudb-mcp-server:latest

# Run with mounted database
docker run -d \
  -p 3000:3000 \
  -v /path/to/your/database:/database \
  -e KUZU_READ_ONLY=false \
  ghcr.io/jordanburke/kuzudb-mcp-server:latest

# Run with custom port and endpoint
docker run -d \
  -p 8080:8080 \
  -v /path/to/your/database:/database \
  -e PORT=8080 \
  ghcr.io/jordanburke/kuzudb-mcp-server:latest \
  node dist/index.js --transport http --port 8080 --endpoint /kuzu

Build Locally

# Build and run with docker-compose (auto-initializes database if needed)
docker-compose up -d

# The init container will:
# - Check if ./data directory contains a database
# - Initialize with movies template if empty
# - Skip initialization if database exists

# Or build manually
docker build -f Dockerfile.http -t kuzu-mcp-http .

# Run your local build
docker run -d \
  -p 3000:3000 \
  -v /path/to/your/database:/database \
  kuzu-mcp-http

# To use a different template or empty database, run init manually first:
docker-compose run kuzu-init node dist/index.js --init /database --template social

The HTTP server will be available at http://localhost:3000/mcp (or your custom endpoint).

HTTP Server Mode

To run the server in HTTP mode:

# Command line
node dist/index.js /path/to/database --transport http --port 3000

# Using npm scripts (with test database)
pnpm serve:test:http

Testing with MCP Inspector

The MCP Inspector is a web-based tool for testing and debugging MCP servers.

# Start server with inspector (automatically opens browser)
pnpm serve:test:inspect

# Or manually:
# 1. Start HTTP server
node dist/index.js /path/to/database --transport http

# 2. Open inspector
npx @modelcontextprotocol/inspector http://localhost:3000/mcp

Remote Client Configuration

For applications supporting HTTP MCP connections:

{
  "mcpServers": {
    "kuzu-remote": {
      "uri": "http://localhost:3000/mcp",
      "transport": "http"
    }
  }
}

HTTP Server Options

• --transport http - Enable HTTP transport (default: stdio)
• --port <number> - HTTP server port (default: 3000)
• --endpoint <path> - Custom endpoint path (default: /mcp)

Example with custom options:

node dist/index.js /path/to/database --transport http --port 8080 --endpoint /kuzu
# Server will be available at http://localhost:8080/kuzu

Multi-Agent Coordination (Experimental)

The server supports multi-agent coordination to allow multiple AI agents (e.g., Claude Desktop and Claude Code) to share the same Kuzu database safely. This feature addresses Kuzu's single-writer limitation through transparent file-based locking.

Enabling Multi-Agent Mode

Set the following environment variables in your configuration:

• KUZU_MULTI_AGENT=true - Enable multi-agent coordination
• KUZU_AGENT_ID=string - Unique identifier for the agent (e.g., "claude-desktop", "claude-code")
• KUZU_LOCK_TIMEOUT=number - Lock timeout in milliseconds (default: 10000)

Claude Desktop Configuration

{
    "mcpServers": {
        "kuzu": {
            "command": "npx",
            "args": ["kuzudb-mcp-server", "/path/to/database"],
            "env": {
                "KUZU_MULTI_AGENT": "true",
                "KUZU_AGENT_ID": "claude-desktop"
            }
        }
    }
}

Claude Code Configuration

{
    "mcpServers": {
        "kuzu": {
            "command": "npx",
            "args": ["kuzudb-mcp-server", "/path/to/database"],
            "env": {
                "KUZU_MULTI_AGENT": "true",
                "KUZU_AGENT_ID": "claude-code"
            }
        }
    }
}

How It Works

When multi-agent mode is enabled:

• Read queries execute immediately without coordination
• Write queries (CREATE, MERGE, SET, DELETE, etc.) acquire an exclusive lock
• Locks are automatically released after query completion
• Stale locks from crashed processes are detected and cleaned up
• Lock conflicts result in clear error messages with retry suggestions

Important Notes

• This feature is experimental and designed for local development scenarios
• Both agents must point to the same database path
• The lock file (.mcp_write_lock) is created in the database directory
• Lock timeout defaults to 10 seconds, which covers most operations

Development

To build from source:

# Clone the repository
git clone https://github.com/jordanburke/kuzudb-mcp-server.git
cd kuzudb-mcp-server

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Run development mode with watch
pnpm run dev

# Run tests and linting
pnpm run lint
pnpm run typecheck
pnpm run format:check

For local development, you can also configure Claude Desktop to use the local build:

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

Web UI for Database Management

The server includes a web-based interface for managing your Kuzu database, automatically enabled when running in HTTP transport mode.

Features

• Database Backup & Restore: Download and upload database backups through your browser
• Direct Database Upload: Upload existing Kuzu database files (main + .wal files) directly
• Visual Database Info: View database path, mode, and connection status
• Secure Access: Optional authentication to protect your database
• Read-Only Mode Support: Upload/restore features automatically disabled in read-only mode

Using the Web UI

The Web UI is automatically enabled when running with HTTP transport.

Quick Start

# Web UI auto-starts on port 3001
pnpm serve:test:http

# Access the web UI
open http://localhost:3001/admin

With Docker Compose

# Start with web UI on port 3001
docker-compose up -d

# Access the web UI
open http://localhost:3001/admin

Disabling the Web UI

To disable the web UI (e.g., for production security):

# Explicitly disable web UI
KUZU_WEB_UI_ENABLED=false \
node dist/index.js test/test-db --transport http

With Authentication

# Add authentication for security
KUZU_WEB_UI_AUTH_USER=admin \
KUZU_WEB_UI_AUTH_PASSWORD=changeme \
node dist/index.js test/test-db --transport http

With Docker

docker run -d \
  -p 3000:3000 \
  -p 3001:3001 \
  -v /path/to/database:/database \
  -e KUZU_WEB_UI_ENABLED=true \
  -e KUZU_WEB_UI_PORT=3001 \
  -e KUZU_WEB_UI_AUTH_USER=admin \
  -e KUZU_WEB_UI_AUTH_PASSWORD=changeme \
  ghcr.io/jordanburke/kuzudb-mcp-server:latest

Web UI Endpoints

• /admin - Main web interface
• /health - Health check endpoint
• /api/info - Database information (JSON)
• /api/backup - Download database backup
• /api/restore - Upload and restore database (supports both backups and raw files)

Uploading Existing Databases

The Web UI supports two methods for uploading databases:

Method 1: Upload Backup File

Upload a .kuzu backup file created by the download feature.

Method 2: Upload Raw Database Files

Upload your existing Kuzu database files directly:

1. Click "Upload" in the web interface
2. Select both files:
   • Your main database file (e.g., memory, mydb.db, etc.)
   • The WAL file if it exists (e.g., memory.wal)
3. The server will restore these files directly

Example: For a database at C:\Users\you\OneDrive\Apps\kuzudb\memory:

• Upload: memory (main file) + memory.wal (WAL file)
• The server replaces its current database with your files

Security Notes

• Web UI is automatically enabled with HTTP transport (disable with KUZU_WEB_UI_ENABLED=false)
• Only available when running with HTTP transport (not with stdio)
• Authentication is strongly recommended for production use
• CORS headers allow cross-origin requests (configure as needed)

Documentation

Core Features

• Connection Recovery - Automatic connection recovery, retry logic, and error handling
• Multi-Agent Coordination - Safe concurrent access with file-based locking
• Batch Query Improvements - Enhanced DDL and multi-statement query handling

Bug Workarounds

• Kuzu Bug Workarounds - Temporary fixes for known Kuzu issues

Environment Variables