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:

Click "Upload" in the web interface
Select both files:
- Your main database file (e.g., memory, mydb.db, etc.)
- The WAL file if it exists (e.g., memory.wal)
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

Variable	Description	Default
`KUZU_READ_ONLY`	Enable read-only mode	`false`
`KUZU_MAX_RETRIES`	Connection recovery retry attempts	`2`
`KUZU_MULTI_AGENT`	Enable multi-agent coordination	`false`
`KUZU_AGENT_ID`	Unique agent identifier	`unknown-{pid}`
`KUZU_LOCK_TIMEOUT`	Lock acquisition timeout (ms)	`10000`
`KUZU_MCP_DATABASE_PATH`	Database path if not provided as argument	-
`KUZU_WEB_UI_ENABLED`	Enable/disable web UI (HTTP mode only)	`true` (auto-enabled with HTTP)
`KUZU_WEB_UI_PORT`	Port for web UI server	`3001`
`KUZU_WEB_UI_AUTH_USER`	Username for web UI authentication	-
`KUZU_WEB_UI_AUTH_PASSWORD`	Password for web UI authentication	-

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

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.

Related MCP Servers

MongoDB
kiliczsh
A
security
A
license
A
quality
A Model Context Protocol server that provides access to MongoDB databases. This server enables LLMs to inspect collection schemas and execute read-only queries.
Last updated -
8
377
261
TypeScript
MIT License
MCP Database Server
manpreet2000
-
security
A
license
-
quality
A Model Context Protocol server that enables LLMs to interact with databases (currently MongoDB) through natural language, supporting operations like querying, inserting, deleting documents, and running aggregation pipelines.
Last updated -
TypeScript
MIT License
MCP TapData Serverofficial
tapdata
-
security
F
license
-
quality
A Model Context Protocol server that enables Large Language Models to access and interact with database connections, including viewing schemas and performing CRUD operations on connected databases.
Last updated -
Couchbase MCP Server for LLMs
Aniket310101
-
security
F
license
-
quality
A Model Context Protocol server that enables large language models to interact directly with Couchbase databases through natural language, supporting operations like querying buckets, performing CRUD operations, and executing N1QL queries.
Last updated -
3
7
TypeScript

View all related MCP servers