Skip to main content
Glama

kuzudb-mcp-server

by jordanburke
npmGitHub
MIT License
5
6
  • Apple
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

kuzudb-mcp-server

A Model Context Protocol server that provides access to Kuzu graph databases. This server enables LLMs to inspect database schemas and execute queries with robust connection recovery, multi-agent coordination, and a built-in web interface.

🚀 Key Features

  • 📊 Web UI: Built-in database management interface with backup/restore capabilities

  • 🔐 Authentication: OAuth and Basic Auth support for secure access

  • 🤝 Multi-Agent: Safe concurrent access from multiple AI agents (experimental)

  • 🔄 Auto-Recovery: Automatic connection recovery with exponential backoff

  • 🐳 Docker Ready: Pre-built images and docker-compose workflow

  • 📱 Dual Transport: Both stdio and HTTP transport modes

  • 🧠 AI-Powered: Natural language to Cypher query generation

Quick Start

Install and Test

# Install globally npm install -g kuzudb-mcp-server # Quick test with auto-created database pnpm serve:test # stdio transport (default) pnpm serve:test:http # HTTP transport with Web UI pnpm serve:test:inspect # HTTP with MCP Inspector # Server management pnpm kill # Stop running servers pnpm restart # Restart with HTTP transport

Development Setup

# Clone and setup git clone https://github.com/jordanburke/kuzudb-mcp-server.git cd kuzudb-mcp-server pnpm install # Initialize databases pnpm db:init # Empty test database pnpm db:init:movies # Sample movie data

One-Line Docker Setup

# Pull and run with mounted database docker run -d -p 3000:3000 -p 3001:3001 \ -v /path/to/your/database:/database \ ghcr.io/jordanburke/kuzudb-mcp-server:latest # Access Web UI at http://localhost:3001/admin # MCP endpoint at http://localhost:3000/mcp

Components

Tools

  • getSchema - Fetch complete database schema (nodes, relationships, properties)

  • query - Execute Cypher queries with automatic error recovery

Prompts

  • generateKuzuCypher - Convert natural language to Kuzu-specific Cypher queries

🖥️ Web UI for Database Management

The server includes a powerful web interface that automatically starts with HTTP transport.

Features

  • 📁 Database Backup & Restore: Download .kuzu backups and restore from browser

  • 📤 Direct File Upload: Upload existing Kuzu database files (main + .wal)

  • 📊 Database Info: View path, mode, connection status, and schema statistics

  • 🔒 Secure Access: Optional authentication protection

  • 👁️ Read-Only Support: Upload/restore disabled in read-only mode

Quick Access

# Start with Web UI (auto-enabled with HTTP) pnpm serve:test:http # Access Web UI open http://localhost:3001/admin

Docker with Web UI

# Using docker-compose (recommended) docker-compose up -d open http://localhost:3001/admin # Manual Docker with Web UI docker run -d \ -p 3000:3000 -p 3001:3001 \ -v /path/to/database:/database \ -e KUZU_WEB_UI_AUTH_USER=admin \ -e KUZU_WEB_UI_AUTH_PASSWORD=changeme \ ghcr.io/jordanburke/kuzudb-mcp-server:latest

API 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

🔐 Authentication & Security

The server supports two authentication methods for different use cases:

OAuth (Production Recommended)

Best for production deployments with token-based security:

# Testing OAuth locally pnpm serve:test:http:oauth # admin/secret123 pnpm serve:test:inspect:oauth # With MCP Inspector # Production OAuth setup KUZU_OAUTH_ENABLED=true \ KUZU_OAUTH_USERNAME=admin \ KUZU_OAUTH_PASSWORD=your-secure-password \ KUZU_OAUTH_USER_ID=admin-user \ KUZU_OAUTH_EMAIL=admin@example.com \ KUZU_JWT_EXPIRES_IN=31536000 \ node dist/index.js /path/to/database --transport http

Basic Auth (Development/Testing)

Simpler setup for development and testing:

# Testing Basic Auth locally pnpm serve:test:http:basic # admin/secret123 pnpm serve:test:inspect:basic # With MCP Inspector # Production Basic Auth setup KUZU_BASIC_AUTH_USERNAME=admin \ KUZU_BASIC_AUTH_PASSWORD=your-secure-password \ KUZU_BASIC_AUTH_USER_ID=admin-user \ KUZU_BASIC_AUTH_EMAIL=admin@example.com \ node dist/index.js /path/to/database --transport http

Web UI Authentication

Secure the Web UI interface:

# Add Web UI authentication KUZU_WEB_UI_AUTH_USER=admin \ KUZU_WEB_UI_AUTH_PASSWORD=changeme \ node dist/index.js /path/to/database --transport http

JWT Token Configuration

Configure JWT token lifetime (OAuth mode only):

# Set token expiration in seconds (default: 31536000 = 1 year) KUZU_JWT_EXPIRES_IN=3600 # 1 hour KUZU_JWT_EXPIRES_IN=86400 # 24 hours KUZU_JWT_EXPIRES_IN=2592000 # 30 days

Security Recommendations

  • Always use authentication for production deployments

  • Use OAuth for external-facing servers

  • Use Basic Auth for internal development/testing

  • Enable Web UI auth when exposing the interface

  • Use HTTPS in production environments

  • Configure JWT expiration based on your security requirements

Usage with Claude Desktop

Docker (Recommended)

{ "mcpServers": { "kuzu": { "command": "docker", "args": [ "run", "-v", "/path/to/database:/database", "--rm", "-i", "ghcr.io/jordanburke/kuzudb-mcp-server:latest" ] } } }

npm/npx

{ "mcpServers": { "kuzu": { "command": "npx", "args": ["kuzudb-mcp-server", "/path/to/database"] } } }

Smithery (Easiest)

# Install via Smithery - includes sample database smithery install kuzudb-mcp-server

Environment Variables

{ "mcpServers": { "kuzu": { "command": "npx", "args": ["kuzudb-mcp-server"], "env": { "KUZU_MCP_DATABASE_PATH": "/path/to/database", "KUZU_READ_ONLY": "true" } } } }

🌐 Remote Connection (HTTP Transport)

Pre-built Docker Images

# Pull latest image docker pull ghcr.io/jordanburke/kuzudb-mcp-server:latest # Run with custom configuration docker run -d \ -p 3000:3000 -p 3001:3001 \ -v /path/to/database:/database \ -e KUZU_READ_ONLY=false \ ghcr.io/jordanburke/kuzudb-mcp-server:latest

Local Development

# HTTP server mode node dist/index.js /path/to/database --transport http --port 3000 # With custom endpoint node dist/index.js /path/to/database --transport http --port 8080 --endpoint /kuzu

MCP Inspector Testing

# Auto-start inspector pnpm serve:test:inspect # Manual setup node dist/index.js /path/to/database --transport http npx @modelcontextprotocol/inspector http://localhost:3000/mcp

Remote Client Configuration

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

🤝 Multi-Agent Coordination (Experimental)

Enable safe concurrent access from multiple AI agents (e.g., 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-desktop", "KUZU_LOCK_TIMEOUT": "10000" } } } }

How It Works

  • Read queries: Execute immediately without coordination

  • Write queries: Acquire exclusive file-based locks

  • Auto cleanup: Stale locks detected and removed

  • Clear errors: Lock conflicts return helpful retry messages

Important Notes

  • Experimental feature for local development

  • Both agents must use the same database path

  • Lock files created in database directory

  • 10-second default timeout covers most operations

🛠️ Development

Build and Test

# Install dependencies pnpm install # Build project pnpm build # Development with watch pnpm dev # Run tests pnpm test pnpm test:ui pnpm test:coverage # Linting and formatting pnpm lint pnpm typecheck pnpm format:check

Local Claude Desktop Setup

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

🔧 Environment Variables Reference

Variable

Description

Default

Usage

Database

KUZU_MCP_DATABASE_PATH

Database path if not in args

-

Startup

KUZU_READ_ONLY

Enable read-only mode

false

Security

Connection

KUZU_MAX_RETRIES

Connection recovery attempts

2

Reliability

Multi-Agent

KUZU_MULTI_AGENT

Enable coordination

false

Concurrency

KUZU_AGENT_ID

Unique agent identifier

unknown-{pid}

Locking

KUZU_LOCK_TIMEOUT

Lock timeout (ms)

10000

Performance

Web UI

KUZU_WEB_UI_ENABLED

Enable/disable Web UI

true

Interface

KUZU_WEB_UI_PORT

Web UI port

3001

Network

KUZU_WEB_UI_AUTH_USER

Web UI username

-

Security

KUZU_WEB_UI_AUTH_PASSWORD

Web UI password

-

Security

Authentication

KUZU_OAUTH_ENABLED

Enable OAuth

false

Security

KUZU_OAUTH_USERNAME

OAuth username

-

Auth

KUZU_OAUTH_PASSWORD

OAuth password

-

Auth

KUZU_BASIC_AUTH_USERNAME

Basic Auth username

-

Auth

KUZU_BASIC_AUTH_PASSWORD

Basic Auth password

-

Auth

🔍 Troubleshooting

Connection Issues

  • "Database connection could not be restored" → Check database file exists and permissions

  • "getAll timeout" → DDL operation hung, server will auto-recover

  • Lock timeout → Another agent writing, wait and retry

Web UI Issues

  • 404 on /admin → Ensure HTTP transport mode is enabled

  • Authentication failing → Check KUZU_WEB_UI_AUTH_* variables

  • Port conflicts → Change KUZU_WEB_UI_PORT or PORT

Docker Issues

  • Health check failing → Verify database mount and port availability

  • Permission errors → Check volume mount permissions

  • Database not found → Ensure correct path mapping

Performance Notes

Based on testing:

  • Simple queries: < 100ms response time

  • Complex multi-hop: 200-500ms response time

  • Schema retrieval: ~100-200ms response time

  • AI query generation: 1-3 seconds (normal for LLM processing)

📚 Documentation

Core Features

Bug Workarounds

Repository: github.com/jordanburke/kuzudb-mcp-server
Docker Images: ghcr.io/jordanburke/kuzudb-mcp-server
Package: npmjs.com/package/kuzudb-mcp-server

This server cannot be installed

-
security - not tested
A
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.

  1. 🚀 Key Features
    1. Quick Start
      1. Install and Test
      2. Development Setup
      3. One-Line Docker Setup
    2. Components
      1. Tools
      2. Prompts
    3. 🖥️ Web UI for Database Management
      1. Features
      2. Quick Access
      3. Docker with Web UI
      4. API Endpoints
    4. 🔐 Authentication & Security
      1. OAuth (Production Recommended)
      2. Basic Auth (Development/Testing)
      3. Web UI Authentication
      4. JWT Token Configuration
      5. Security Recommendations
    5. Usage with Claude Desktop
      1. Docker (Recommended)
      2. npm/npx
      3. Smithery (Easiest)
      4. Environment Variables
    6. 🌐 Remote Connection (HTTP Transport)
      1. Pre-built Docker Images
      2. Local Development
      3. MCP Inspector Testing
      4. Remote Client Configuration
    7. 🤝 Multi-Agent Coordination (Experimental)
      1. Configuration
      2. How It Works
      3. Important Notes
    8. 🛠️ Development
      1. Build and Test
      2. Local Claude Desktop Setup
    9. 🔧 Environment Variables Reference
      1. 🔍 Troubleshooting
        1. Connection Issues
        2. Web UI Issues
        3. Docker Issues
        4. Performance Notes
      2. 📚 Documentation
        1. Core Features
        2. Bug Workarounds

      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
        280
        263
        MIT License
        • Apple

      • 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 -
        MIT License
        • Apple

      • 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 -
        • Apple

      • 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 -
        21
        7
        • Apple

      View all related MCP servers

      New MCP Servers

      MCP directory API

      We provide all the information about MCP servers via our MCP API.

      curl -X GET 'https://glama.ai/api/mcp/v1/servers/jordanburke/kuzudb-mcp-server'

      If you have feedback or need assistance with the MCP directory API, please join our Discord server