kuzudb-mcp-server

⚠️ ARCHIVED: This project is archived as the Kuzu database repository was archived on October 10, 2025. See ARCHIVE_NOTICE.md for details and alternatives.

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.

Archive Status

Archived - October 21, 2025

The Kuzu graph database repository was archived by its maintainers on October 10, 2025 and is now read-only. As Kuzu is no longer actively maintained, this MCP server is also being archived. The project remains fully functional with Kuzu v1.4.1-r.4. See ARCHIVE_NOTICE.md for full details, technical achievements, and alternative graph database options.

Related MCP server: MCP Database Server

🚀 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

Connection Recovery - Automatic recovery and retry logic
Multi-Agent Coordination - Concurrent access design
Batch Query Improvements - DDL and multi-statement handling

Bug Workarounds

Kuzu Bug Workarounds - Known issue fixes

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