home / mcp / kuzudb mcp server

Kuzudb MCP Server

A Model Context Protocol server that provides access to Kuzu databases

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "jordanburke-kuzudb-mcp-server": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "KUZU_AGENT_ID": "claude-desktop",
        "KUZU_READ_ONLY": "false",
        "KUZU_MULTI_AGENT": "false",
        "KUZU_WEB_UI_PORT": "3001",
        "KUZU_LOCK_TIMEOUT": "10000",
        "KUZU_OAUTH_ENABLED": "false",
        "KUZU_JWT_EXPIRES_IN": "31536000",
        "KUZU_OAUTH_PASSWORD": "your-secure-password",
        "KUZU_OAUTH_USERNAME": "admin",
        "KUZU_WEB_UI_ENABLED": "true",
        "KUZU_WEB_UI_AUTH_USER": "admin",
        "KUZU_MCP_DATABASE_PATH": "'/path/to/database'",
        "KUZU_BASIC_AUTH_PASSWORD": "your-secure-password",
        "KUZU_BASIC_AUTH_USERNAME": "admin",
        "KUZU_WEB_UI_AUTH_PASSWORD": "changeme"
      }
    }
  }
}

You can run kuzudb-mcp-server to expose access to Kuzu graph databases for large language models and automation. It provides a web UI, secure authentication, automatic connection recovery, and multi-agent coordination, enabling safe and scalable querying and schema inspection from your MCP clients.

How to use

To work with an MCP client, you connect to kuzudb-mcp-server either over HTTP or via a local standard input/output (stdio) transport. You can run the server in a Docker container for quick deployment or install it globally to use from your system shell. Once the server is running, you can inspect the database schema, execute Cypher queries, and generate Kuzu Cypher from natural language. The built-in Web UI provides database management, backups, and restores, while authentication protects access in production.

Typical usage patterns: - Run in HTTP mode to expose a MCP endpoint and use the Web UI for administration. - Use the stdio transport for local workflows or editor integrations that spawn the MCP server as a child process. - Enable multi-agent coordination for concurrent work from multiple AI agents, with coordination controls and timeouts.

How to install

Prerequisites: ensure you have Node.js and npm installed on your system. You can also use pnpm if you prefer.

Install the MCP server globally with npm and verify the installer is available on your path.

# Install globally
npm install -g kuzudb-mcp-server

Optionally, you can use pnpm to run quick tests or development scripts that exercise the MCP server locally.

# Quick test with auto-created database (stdio transport)
pnpm serve:test

# Quick test with HTTP transport and Web UI
pnpm serve:test:http

# Start an inspector-enabled HTTP server for debugging
pnpm serve:test:inspect

For Docker-based usage, pull and run the pre-built image with a mounted database. The server exposes the MCP endpoint at port 3000 and the Web UI at port 3001.

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

Additional setup notes

If you prefer a custom docker-compose workflow, you can start with a docker-compose.yml that defines the same port mappings and volume mounts shown above.

Available tools

getSchema

Fetch complete database schema including nodes, relationships, and properties.

query

Execute Cypher queries with automatic error recovery.

generateKuzuCypher

Convert natural language prompts into Kuzu-specific Cypher queries.