昆布数据库-MCP服务器

Name: 昆布数据库-MCP服务器
Author: jordanburke

作者：jordanburke7 星标更新：2025-10-22

安装使用来源：spider==github.com

项目介绍

技术文档摘要

kuzudb-mcp-server

⚠️ 已归档: 此项目已归档，因为Kuzu数据库仓库已于2025年10月10日被归档。详情及替代方案见ARCHIVE_NOTICE.md。

一个提供对Kuzu图数据库访问的模型上下文协议服务器。此服务器使LLMs能够检查数据库模式并执行查询，具有强大的连接恢复、多代理协调以及内置的Web界面功能。

归档状态

已归档 - 2025年10月21日

Kuzu图数据库仓库由其维护者于2025年10月10日归档，并且现在是只读的。由于Kuzu不再积极维护，此MCP服务器也被归档。该项目与Kuzu v1.4.1-r.4完全兼容。详情、技术成就及替代图数据库选项见ARCHIVE_NOTICE.md。

🚀 主要特性

📊 Web UI: 内置数据库管理界面，具备备份/恢复功能
🔐 认证: 支持OAuth和Basic Auth的安全访问
🤝 多代理: 多个AI代理的安全并发访问（实验性）
🔄 自动恢复: 具有指数退避的自动连接恢复
🐳 Docker就绪: 预构建镜像和docker-compose工作流
📱 双传输: 同时支持stdio和HTTP传输模式
🧠 AI驱动: 自然语言到Cypher查询生成

快速开始

安装和测试

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

# 快速测试，自动生成数据库
pnpm serve:test              # stdio传输（默认）
pnpm serve:test:http         # 带Web UI的HTTP传输
pnpm serve:test:inspect      # 带MCP Inspector的HTTP传输

# 服务器管理
pnpm kill    # 停止运行中的服务器
pnpm restart # 使用HTTP传输重启

开发设置

# 克隆并设置
git clone https://github.com/jordanburke/kuzudb-mcp-server.git
cd kuzudb-mcserver
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 UI
# MCP端点在http://localhost:3000/mcp

组件

工具

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

提示

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

🖥️ 数据库管理Web UI

服务器包含一个强大的Web界面，它会随着HTTP传输自动启动。

功能

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

快速访问

# 启动带Web UI（HTTP自动启用）
pnpm serve:test:http

# 访问Web UI
open http://localhost:3001/admin

带Web UI的Docker

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

# 手动Docker带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端点

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

🔐 认证与安全

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

OAuth（生产推荐）

适用于基于令牌的安全生产部署：

# 本地测试OAuth
pnpm serve:test:http:oauth     # admin/secret123
pnpm serve:test:inspect:oauth  # 带MCP Inspector

# 生产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 \
KUZU_JWT_EXPIRES_IN=31536000 \
node dist/index.js /path/to/database --transport http

Basic Auth（开发/测试）

开发和测试的简单设置：

# 本地测试Basic Auth  
pnpm serve:test:http:basic     # admin/secret123
pnpm serve:test:inspect:basic  # 带MCP Inspector

# 生产Basic Auth设置
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认证

保护Web UI界面：

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

JWT令牌配置

配置JWT令牌生命周期（仅限OAuth模式）：

# 设置令牌过期时间（秒，默认：31536000 = 1年）
KUZU_JWT_EXPIRES_IN=3600    # 1小时
KUZU_JWT_EXPIRES_IN=86400   # 24小时
KUZU_JWT_EXPIRES_IN=2592000 # 30天

安全建议

始终使用认证用于生产部署
使用OAuth对外部服务器
使用Basic Auth用于内部开发/测试
启用Web UI认证当暴露接口时
使用HTTPS在生产环境中
根据安全需求配置JWT过期时间

与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 Inspector测试

# 自动启动Inspector
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 UI
`KUZU_WEB_UI_ENABLED`	启用/禁用Web UI	`true`	接口
`KUZU_WEB_UI_PORT`	Web UI端口	`3001`	网络
`KUZU_WEB_UI_AUTH_USER`	Web UI用户名	-	安全
`KUZU_WEB_UI_AUTH_PASSWORD`	Web UI密码	-	安全
认证
`KUZU_OAUTH_ENABLED`	启用OAuth	`false`	安全
`KUZU_OAUTH_USERNAME`	OAuth用户名	-	认证
`KUZU_OAUTH_PASSWORD`	OAuth密码	-	认证
`KUZU_BASIC_AUTH_USERNAME`	Basic Auth用户名	-	认证
`KUZU_BASIC_AUTH_PASSWORD`	Basic Auth密码	-	认证

🔍 故障排除

连接问题

"无法恢复数据库连接" → 检查数据库文件是否存在及权限
"getAll超时" → DDL操作挂起，服务器将自动恢复
锁超时 → 另一个代理正在写入，请等待并重试

Web UI问题

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

Docker问题

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

性能提示

基于测试：

简单查询: < 100毫秒响应时间
复杂多跳: 200-500毫秒响应时间
模式检索: ~100-200毫秒响应时间
AI查询生成: 1-3秒（正常LLM处理时间）

📚 文档

核心功能

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

Bug解决办法

Kuzu Bug解决办法 - 已知问题修复

仓库: github.com/jordanburke/kuzudb-mcp-server
Docker镜像: ghcr.io/jordanburke/kuzudb-mcp-server
包: npmjs.com/package/kuzudb-mcp-server