Kuzudb MCP Server

🚀 kuzudb-mcp-server

Kuzuグラフデータベースへのアクセスを提供するModel Context Protocolサーバーです。このサーバーは、LLMがデータベーススキーマを調査し、クエリを実行できるようにし、強力な接続回復機能、マルチエージェント協調機能、および組み込みのWebインターフェイスを備えています。

✨ 主な機能

• 📊 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インスペクター付きの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

# Web UIには http://localhost:3001/admin でアクセス
# 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

DockerでのWeb UIの使用

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

# Web UI付きの手動Docker
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 - データベースをアップロードして復元

🔐 認証とセキュリティ

サーバーは、さまざまなユースケースに対応する2つの認証方法をサポートしています。

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

Basic Auth（開発/テスト）

開発とテスト用のシンプルなセットアップです。

# ローカルでBasic Authをテスト
pnpm serve:test:http:basic     # admin/secret123
pnpm serve:test:inspect:basic  # MCPインスペクター付き

# 本番環境の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

セキュリティ推奨事項

• 本番環境のデプロイでは常に認証を使用してください。
• 外部に公開されるサーバーではOAuthを使用してください。
• 内部の開発/テストではBasic Authを使用してください。
• インターフェイスを公開する場合はWeb UI認証を有効にする。
• 本番環境では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 UIの問題

• /adminで404エラー → HTTPトランスポートモードが有効になっていることを確認してください。
• 認証が失敗する → KUZU_WEB_UI_AUTH_*変数を確認してください。
• ポートの競合 → KUZU_WEB_UI_PORTまたはPORTを変更してください。

Dockerの問題

• ヘルスチェックが失敗する → データベースのマウントとポートの可用性を確認してください。
• パーミッションエラー → ボリュームマウントのパーミッションを確認してください。
• データベースが見つからない → 正しいパスマッピングを確認してください。

パフォーマンスに関する注意事項

テストに基づくと：

• 単純なクエリ：応答時間 < 100ms
• 複雑なマルチホップ：応答時間200 - 500ms
• スキーマの取得：応答時間 ~100 - 200ms
• AIクエリ生成：1 - 3秒（LLM処理には通常）

ドキュメント

主要機能

• 接続回復 - 自動回復と再試行ロジック
• マルチエージェント協調 - 同時アクセス設計
• バッチクエリの改善 - DDLとマルチステートメントの処理

バグの回避策

• Kuzuバグの回避策 - 既知の問題の修正

リポジトリ: github.com/jordanburke/kuzudb-mcp-server
Dockerイメージ: ghcr.io/jordanburke/kuzudb-mcp-server
パッケージ: npmjs.com/package/kuzudb-mcp-server