Kuzudb Mcp Server

Kuzudb Mcp Server

数据库 TypeScript

🚀 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 启用只读模式
连接
KUZU_MAX_RETRIES 连接恢复尝试次数
多智能体
KUZU_MULTI_AGENT 启用协调功能
KUZU_AGENT_ID 唯一的智能体标识符
KUZU_LOCK_TIMEOUT 锁超时时间（毫秒）
Web 界面
KUZU_WEB_UI_ENABLED 启用/禁用 Web 界面
KUZU_WEB_UI_PORT Web 界面端口
KUZU_WEB_UI_AUTH_USER Web 界面用户名
KUZU_WEB_UI_AUTH_PASSWORD Web 界面密码
认证
KUZU_OAUTH_ENABLED 启用 OAuth
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

默认排序 时间排序

0 个评论

« 上一篇
Ollama PostgreSQL Data Analysis
下一篇 »
Hasura GraphQL
  • 0 关注
  • 0 收藏，15 浏览
  • system 提出于 2025-09-24 12:39

相似服务问题

相关AI产品

  • 暂无相关AI产品

热议话题 »