Kuzudb MCP Server

🚀 kuzudb-mcp-server

kuzudb-mcp-server 是一个模型上下文协议（MCP）服务器，用于接入 Kuzu 图数据库。该服务器使大语言模型（LLMs）能够检查数据库模式并执行查询，具备强大的连接恢复能力、多智能体协调功能，还自带一个 Web 界面。

🚀 快速开始

安装与测试

# 全局安装
npm install -g kuzudb-mcp-server

# 用自动创建的数据库进行快速测试
pnpm serve:test              # 标准输入输出传输（默认）
pnpm serve:test:http         # 带 Web 界面的 HTTP 传输
pnpm serve:test:inspect      # 带 MCP 检查器的 HTTP 传输

# 服务器管理
pnpm kill    # 停止正在运行的服务器
pnpm restart # 以 HTTP 传输方式重启

开发环境设置

# 克隆并设置
git clone https://github.com/jordanburke/kuzudb-mcp-server.git
cd kuzudb-mcp-server
pnpm install

# 初始化数据库
pnpm db:init                 # 空的测试数据库
pnpm db:init:movies          # 示例电影数据

一键式 Docker 设置

# 拉取并挂载数据库运行
docker run -d -p 3000:3000 -p 3001:3001 \
  -v /path/to/your/database:/database \
  ghcr.io/jordanburke/kuzudb-mcp-server:latest

# 在 http://localhost:3001/admin 访问 Web 界面
# MCP 端点在 http://localhost:3000/mcp

✨ 主要特性

• 📊 Web 界面：内置数据库管理界面，具备备份/恢复功能
• 🔐 认证：支持 OAuth 和基本认证，确保安全访问
• 🤝 多智能体：支持多个 AI 智能体安全并发访问（实验性）
• 🔄 自动恢复：通过指数退避算法实现自动连接恢复
• 🐳 Docker 就绪：提供预构建镜像和 docker-compose 工作流
• 📱 双传输模式：支持标准输入输出和 HTTP 两种传输模式
• 🧠 人工智能驱动：可将自然语言转换为 Cypher 查询

📦 安装指南

全局安装

npm install -g kuzudb-mcp-server

Docker 安装

docker run -d -p 3000:3000 -p 3001:3001 \
  -v /path/to/your/database:/database \
  ghcr.io/jordanburke/kuzudb-mcp-server:latest

💻 使用示例

基础用法

可使用以下命令启动服务器进行快速测试：

# 标准输入输出传输（默认）
pnpm serve:test

# 带 Web 界面的 HTTP 传输
pnpm serve:test:http

# 带 MCP 检查器的 HTTP 传输
pnpm serve:test:inspect

高级用法

在开发环境中，可按以下步骤设置：

# 克隆并设置
git clone https://github.com/jordanburke/kuzudb-mcp-server.git
cd kuzudb-mcp-server
pnpm install

# 初始化数据库
pnpm db:init                 # 空的测试数据库
pnpm db:init:movies          # 示例电影数据

# 启动开发服务器
pnpm dev

📚 详细文档

组件

工具

• getSchema - 获取完整的数据库模式（节点、关系、属性）
• query - 执行 Cypher 查询，并具备自动错误恢复功能

提示

• generateKuzuCypher - 将自然语言转换为 Kuzu 特定的 Cypher 查询

Web 界面数据库管理

服务器包含一个强大的 Web 界面，在使用 HTTP 传输时会自动启动。

功能

• 📁 数据库备份与恢复：可从浏览器下载 .kuzu 备份文件并进行恢复
• 📤 直接文件上传：上传现有的 Kuzu 数据库文件（主文件 + .wal）
• 📊 数据库信息：查看路径、模式、连接状态和模式统计信息
• 🔒 安全访问：可选的认证保护
• 👁️ 只读支持：在只读模式下禁用上传/恢复功能

快速访问

# 启动带 Web 界面的服务器（HTTP 自动启用）
pnpm serve:test:http

# 访问 Web 界面
open http://localhost:3001/admin

Docker 与 Web 界面

# 使用 docker-compose（推荐）
docker-compose up -d
open http://localhost:3001/admin

# 手动使用 Docker 并启用 Web 界面
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 端点

• /admin - 主 Web 界面
• /health - 健康检查端点
• /api/info - 数据库信息（JSON 格式）
• /api/backup - 下载数据库备份
• /api/restore - 上传并恢复数据库

认证与安全

服务器支持两种认证方法，适用于不同的使用场景：

OAuth（推荐用于生产环境）

对于基于令牌的安全生产部署，OAuth 是最佳选择：

# 在本地测试 OAuth
pnpm serve:test:http:oauth     # 用户名/密码：admin/secret123
pnpm serve:test:inspect:oauth  # 带 MCP 检查器

# 生产环境 OAuth 设置
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 \
node dist/index.js /path/to/database --transport http

基本认证（用于开发/测试）

对于开发和测试，基本认证的设置更简单：

# 在本地测试基本认证
pnpm serve:test:http:basic     # 用户名/密码：admin/secret123
pnpm serve:test:inspect:basic  # 带 MCP 检查器

# 生产环境基本认证设置
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 界面认证

为 Web 界面添加认证保护：

# 添加 Web 界面认证
KUZU_WEB_UI_AUTH_USER=admin \
KUZU_WEB_UI_AUTH_PASSWORD=changeme \
node dist/index.js /path/to/database --transport http

安全建议

• 生产环境始终使用认证
• 面向外部的服务器使用 OAuth
• 内部开发/测试使用基本认证
• 公开界面时启用 Web 界面认证
• 生产环境使用 HTTPS

与 Claude Desktop 配合使用

Docker（推荐）

{
  "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（最简单）

# 通过 Smithery 安装 - 包含示例数据库
smithery install kuzudb-mcp-server

环境变量

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

远程连接（HTTP 传输）

预构建 Docker 镜像

# 拉取最新镜像
docker pull ghcr.io/jordanburke/kuzudb-mcp-server:latest

# 使用自定义配置运行
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

本地开发

# HTTP 服务器模式
node dist/index.js /path/to/database --transport http --port 3000

# 使用自定义端点
node dist/index.js /path/to/database --transport http --port 8080 --endpoint /kuzu

MCP 检查器测试

# 自动启动检查器
pnpm serve:test:inspect

# 手动设置
node dist/index.js /path/to/database --transport http
npx @modelcontextprotocol/inspector http://localhost:3000/mcp

远程客户端配置

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

多智能体协调（实验性）

启用多个 AI 智能体（如 Claude Desktop + Claude Code）的安全并发访问：

配置

{
  "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"
      }
    }
  }
}

工作原理

• 读查询：无需协调，立即执行
• 写查询：获取基于文件的排他锁
• 自动清理：检测并移除过期锁
• 清除错误：锁冲突返回有用的重试消息

重要说明

• 实验性功能，用于本地开发
• 两个智能体必须使用相同的数据库路径
• 锁文件在数据库目录中创建
• 默认 10 秒超时可覆盖大多数操作

🔧 技术细节

开发

构建与测试

# 安装依赖
pnpm install

# 构建项目
pnpm build

# 开发模式并监听文件变化
pnpm dev

# 运行测试
pnpm test
pnpm test:ui
pnpm test:coverage

# 代码检查和格式化
pnpm lint
pnpm typecheck
pnpm format:check

本地 Claude Desktop 设置

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

环境变量参考

故障排除

连接问题

• “无法恢复数据库连接” → 检查数据库文件是否存在以及权限设置
• “getAll 超时” → DDL 操作挂起，服务器将自动恢复
• 锁超时 → 另一个智能体正在写入，等待并重试

Web 界面问题

• /admin 页面返回 404 → 确保启用了 HTTP 传输模式
• 认证失败 → 检查 KUZU_WEB_UI_AUTH_* 变量
• 端口冲突 → 更改 KUZU_WEB_UI_PORT 或 PORT

Docker 问题

• 健康检查失败 → 验证数据库挂载和端口可用性
• 权限错误 → 检查卷挂载权限
• 找不到数据库 → 确保路径映射正确

性能说明

根据测试：

• 简单查询：响应时间 < 100 毫秒
• 复杂多跳查询：响应时间 200 - 500 毫秒
• 模式检索：响应时间约 100 - 200 毫秒
• AI 查询生成：1 - 3 秒（大语言模型处理正常时间）

文档

核心特性

• 连接恢复 - 自动恢复和重试逻辑
• 多智能体协调 - 并发访问设计
• 批量查询改进 - DDL 和多语句处理

漏洞解决方法

• Kuzu 漏洞解决方法 - 已知问题修复

仓库地址：github.com/jordanburke/kuzudb-mcp-server
Docker 镜像：ghcr.io/jordanburke/kuzudb-mcp-server
npm 包：npmjs.com/package/kuzudb-mcp-server