Kuzudb MCP Server

Kuzudb-Mcp-Server（或可译为“Kuzu数据库MCP服务器”，具体译名可能根据上下文调整）

⚠️ 已归档此项目已归档，因为Kuzu数据库仓库已于2025年10月10日归档。请参阅 ARCHIVE_NOTICE.md 翻译为中文是：“存档通知文件（Markdown 格式）” 以了解详细信息和备选方案。

______________________________________________________________________

一个模型上下文协议服务器，提供对Kuzu图数据库的访问。该服务器使大型语言模型（LLMs）能够检查数据库模式，并执行查询，同时具备强大的连接恢复能力、多智能体协调功能以及内置的网页界面。

存档状态

已存档 - 2025年10月21日

Kuzu图数据库仓库已于2025年10月10日由其维护者存档，现已设为只读模式。由于Kuzu不再积极维护，因此该MCP服务器也正在被存档。使用Kuzu v1.4.1-r.4版本，该项目仍可完全正常运行。详见 \ARCHIVE_NOTICE.md\ 翻译为中文是：“归档通知文件（Markdown 格式）” 如需详细了解、技术成果及其他图数据库选项，请参阅。

🚀 主要特点

• 📊 Web用户界面（Web UI）内置数据库管理接口，具备备份/恢复功能
• 🔐 身份验证支持OAuth和基本认证以实现安全访问
• 🤝 多智能体多个AI代理安全并发访问（实验性）
• 🔄 自动恢复自动连接恢复，采用指数退避策略
• 🐳 Docker 准备就绪预构建的镜像和docker-compose工作流
• 📱 双重传输标准I/O（stdio）和HTTP传输模式均支持
• 🧠 人工智能驱动自然语言到Cypher查询的生成

快速入门

安装并测试

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

# Quick test with auto-created database
pnpm serve:test              # stdio transport (default)
pnpm serve:test:http         # HTTP transport with Web UI
pnpm serve:test:inspect      # HTTP with MCP Inspector

# Server management
pnpm kill    # Stop running servers
pnpm restart # Restart with HTTP transport

开发环境设置

# Clone and setup
git clone https://github.com/jordanburke/kuzudb-mcp-server.git
cd kuzudb-mcp-server
pnpm install

# Initialize databases
pnpm db:init                 # Empty test database
pnpm db:init:movies          # Sample movie data

一键式Docker设置

# Pull and run with mounted database
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

组件

工具

• 获取模式（或架构） - 获取完整的数据库架构（节点、关系、属性）
• 查询 - 执行带有自动错误恢复的Cypher查询

提示

• 生成KuzuCypher（或根据上下文，可译为“生成Kuzu密码”或“创建KuzuCypher”） - 将自然语言转换为Kuzu特定的Cypher查询

🖥️ 数据库管理的Web用户界面

该服务器包含一个功能强大的网页界面，该界面会随HTTP传输自动启动。

特性/特点

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

快速访问

# Start with Web UI (auto-enabled with HTTP)
pnpm serve:test:http

# Access Web UI
open http://localhost:3001/admin

带有Web用户界面的Docker

# Using docker-compose (recommended)
docker-compose up -d
open http://localhost:3001/admin

# Manual Docker with 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 - 主网页界面
• /health - 健康检查端点
• /api/info - 数据库信息（JSON格式）
• /api/backup - 下载数据库备份
• /api/restore - 上传并恢复数据库

🔐 认证与安全

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

OAuth（生产环境推荐）

最适合采用基于令牌的安全机制的生产环境部署：

# Testing OAuth locally
pnpm serve:test:http:oauth     # admin/secret123
pnpm serve:test:inspect:oauth  # With MCP Inspector

# Production OAuth setup
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

基本认证（开发/测试）

更简便的开发和测试设置：

# Testing Basic Auth locally  
pnpm serve:test:http:basic     # admin/secret123
pnpm serve:test:inspect:basic  # With MCP Inspector

# Production Basic Auth setup
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用户界面的安全性：

# Add Web UI authentication
KUZU_WEB_UI_AUTH_USER=admin \
KUZU_WEB_UI_AUTH_PASSWORD=changeme \
node dist/index.js /path/to/database --transport http

JWT Token 配置

配置JWT令牌有效期（仅限OAuth模式）：

# Set token expiration in seconds (default: 31536000 = 1 year)
KUZU_JWT_EXPIRES_IN=3600    # 1 hour
KUZU_JWT_EXPIRES_IN=86400   # 24 hours
KUZU_JWT_EXPIRES_IN=2592000 # 30 days

安全建议

• 始终使用身份验证 用于生产环境部署
• 使用OAuth 用于面向外部的服务器
• 使用基本身份验证 用于内部开发/测试
• 启用Web UI认证 在暴露接口时
• 使用HTTPS 在生产环境中
• 配置JWT过期时间 基于您的安全要求

与Claude桌面版的使用

Docker（推荐）

{
  "mcpServers": {
    "kuzu": {
      "command": "docker",
      "args": [
        "run", "-v", "/path/to/database:/database",
        "--rm", "-i", "ghcr.io/jordanburke/kuzudb-mcp-server:latest"
      ]
    }
  }
}

npm/npx（注：这已经是中文表述，但为符合要求，可解释为）npm（Node包管理器）/npx（用于运行npm包中的可执行文件）

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

史密斯里（最容易）

# Install via Smithery - includes sample database
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 镜像

# Pull latest image
docker pull ghcr.io/jordanburke/kuzudb-mcp-server:latest

# Run with custom configuration
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 server mode
node dist/index.js /path/to/database --transport http --port 3000

# With custom endpoint
node dist/index.js /path/to/database --transport http --port 8080 --endpoint /kuzu

MCP检查员测试

# Auto-start inspector
pnpm serve:test:inspect

# Manual setup
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秒的默认超时时间可覆盖大多数操作

🛠️ 开发

构建与测试

# Install dependencies
pnpm install

# Build project
pnpm build

# Development with watch
pnpm dev

# Run tests
pnpm test
pnpm test:ui
pnpm test:coverage

# Linting and formatting
pnpm lint
pnpm typecheck
pnpm format:check

本地Claude桌面设置

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

🔧 环境变量参考

🔍 故障排除

连接问题

• “数据库连接无法恢复” → 检查数据库文件是否存在及权限设置
• “getAll timeout”翻译成中文是“获取全部超时” → 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的临时解决方案（或：Kuzu的变通方法） - 已知问题修复

______________________________________________________________________

仓库（或存储库）: \ Docker 镜像： ghcr.io/jordanburke/kuzudb-mcp-server 翻译为中文是：“ghcr.io 网站上的 jordanburke 用户的 kuzudb-mcp-server 镜像”。不过，通常在技术或软件领域，这样的表述可能会简化为“ghcr.io 上的 jordanburke/kuzudb-mcp-server 镜像”，以更简洁地传达信息\ 包裹；软件包；程序包：