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