JinDaGe - kuzudb-mcp-server MCP Details

article

README

🚀 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"
      ]
    }
  }
}

环境变量参考

| 属性 | 详情 | |------|------| | 数据库 | | KUZU_MCP_DATABASE_PATH | 若未在参数中指定，此为数据库路径 | - | 启动时使用 | | KUZU_READ_ONLY | 启用只读模式 | false | 安全相关 | | 连接 | | KUZU_MAX_RETRIES | 连接恢复尝试次数 | 2 | 可靠性相关 | | 多智能体 | | KUZU_MULTI_AGENT | 启用协调功能 | false | 并发相关 | | KUZU_AGENT_ID | 唯一的智能体标识符 | unknown-{pid} | 锁机制相关 | | KUZU_LOCK_TIMEOUT | 锁超时时间（毫秒） | 10000 | 性能相关 | | Web 界面 | | KUZU_WEB_UI_ENABLED | 启用/禁用 Web 界面 | true | 界面相关 | | KUZU_WEB_UI_PORT | Web 界面端口 | 3001 | 网络相关 | | KUZU_WEB_UI_AUTH_USER | Web 界面用户名 | - | 安全相关 | | KUZU_WEB_UI_AUTH_PASSWORD | Web 界面密码 | - | 安全相关 | | 认证 | | KUZU_OAUTH_ENABLED | 启用 OAuth | false | 安全相关 | | KUZU_OAUTH_USERNAME | OAuth 用户名 | - | 认证相关 | | KUZU_OAUTH_PASSWORD | OAuth 密码 | - | 认证相关 | | KUZU_BASIC_AUTH_USERNAME | 基本认证用户名 | - | 认证相关 | | KUZU_BASIC_AUTH_PASSWORD | 基本认证密码 | - | 认证相关 |

故障排除

连接问题

“无法恢复数据库连接” → 检查数据库文件是否存在以及权限设置
“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