SurrealDB MCP Server

SurrealDB MCP サーバー

AI アシスタントが SurrealDB データベースとやり取りするための標準インターフェースを提供する、Model Context Protocol（MCP）サーバーです。このサーバーを使うと、AI システムから、設定済みの SurrealDB インスタンス内のデータをクエリおよび操作できます。

AI アシスタントへの注意： Claude、Cline、Copilot などの AI アシスタントとしてこのドキュメントを読んでいる場合は、この MCP サーバーのインストールと設定をユーザーに案内するために用意された詳しい手順が記載されている llms-install.md ファイルを参照してください。

インストールガイド

使用している AI アシスタントはどれですか？

• 📝 Cline VS Code Extension を使用していますか？ → Cline のインストールへ
• 🖥️ Claude Desktop App を使用していますか？ → Claude のインストールへ
• 🤖 VS Code で GitHub Copilot を使用していますか？ → Copilot のインストールへ
• 🦘 VS Code で Roo Code を使用していますか？ → Roo Code のインストールへ
• 🌊 Windsurf を使用していますか？ → Windsurf のインストールへ
• ⚡ Cursor を使用していますか？ → Cursor のインストールへ
• 🔄 n8n を使用していますか？ → n8n との連携へ

主な用語

• MCP サーバー：Model Context Protocol を実装し、AI アシスタントが外部のツールやリソースにアクセスできるようにするサーバー
• MCP ホスト：MCP サーバーに接続するアプリケーション（Cline を使用する VS Code や Claude Desktop など）
• SurrealDB：リアルタイム機能を備えた、スケーラブルな分散型ドキュメントグラフデータベース

利用可能なツール

このサーバーは、SurrealDB とやり取りするための以下のツールを公開します。

• query：SurrealQL の生クエリを実行します。
• select：テーブルからレコードを選択します（すべて、または特定の ID を指定）。
• create：テーブルに新しいレコードを 1 件作成します。
• update：特定のレコードを更新し、その内容を置き換えます。
• delete：ID を指定して特定のレコードを削除します。
• merge：特定のレコードにデータをマージします（一部更新）。
• patch：特定のレコードに JSON Patch 操作を適用します。
• upsert：レコードが存在しない場合は作成し、存在する場合は更新します。
• insert：テーブルに複数のレコードを挿入します。
• insertRelation：2 つのレコード間にグラフリレーション（エッジ）を作成します。

(詳しい入力スキーマについては、MCP ホストのツール一覧を参照してください。)

📝 Cline のインストール

Cline VS Code Extension のワンクリックインストール

1. パッケージをグローバルにインストールします。

   npm install -g surrealdb-mcp-server
   

2. Cline の設定に追加します。

   次のファイルを編集します：%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

   以下の設定を追加します。

   {
     "mcpServers": {
       "surrealdb": {
         "command": "C:\\Program Files\\nodejs\\node.exe",
         "args": [
           "C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\npm\\node_modules\\surrealdb-mcp-server\\build\\index.js"
         ],
         "env": {
           "SURREALDB_URL": "ws://localhost:8000",
           "SURREALDB_NS": "your_namespace",
           "SURREALDB_DB": "your_database",
           "SURREALDB_USER": "your_db_user",
           "SURREALDB_PASS": "your_db_password"
         },
         "disabled": false,
         "autoApprove": []
       }
     }
   }
   

   重要： パス内の YOUR_USERNAME を実際の Windows ユーザー名に置き換えてください。

3. VS Code を再起動します。

4. インストールを確認します。

   • VS Code で Cline を開きます。
   • Cline に「利用可能な MCP サーバーを一覧表示して」と尋ねます。
   • 一覧に「surrealdb」が表示されていることを確認します。

🖥️ Claude のインストール

Claude Desktop App へのインストール

1. サーバーを使用するように Claude Desktop を設定します：

   Claude Desktop App の MCP 設定ファイルを編集します：

   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

   次の設定を追加します：

   {
     "mcpServers": {
       "surrealdb": {
         "command": "npx",
         "args": [
           "-y",
           "surrealdb-mcp-server"
         ],
         "env": {
           "SURREALDB_URL": "ws://localhost:8000",
           "SURREALDB_NS": "your_namespace",
           "SURREALDB_DB": "your_database",
           "SURREALDB_USER": "your_db_user",
           "SURREALDB_PASS": "your_db_password"
         },
         "disabled": false,
         "autoApprove": []
       }
     }
   }
   

   注意： 上記のように npx コマンドを使用すると、必要に応じて MCP クライアントが npm からパッケージを自動的にダウンロードして実行します。手動でインストールする必要はありません。

2. Claude Desktop App を再起動します

3. インストールを確認します：

   • Claude に「利用可能な MCP サーバーを一覧表示して」と尋ねます
   • 一覧に「surrealdb」が表示されることを確認します

🤖 Copilot のインストール

VS Code の GitHub Copilot へのインストール

1. ワークスペース設定ファイルを作成します：

   ワークスペースに .vscode/mcp.json ファイルを作成します

   次の設定を追加します：

   {
     "inputs": [
       {
         "type": "promptString",
         "id": "surrealdb-url",
         "description": "SurrealDB URL",
         "default": "ws://localhost:8000"
       },
       {
         "type": "promptString",
         "id": "surrealdb-ns",
         "description": "SurrealDB Namespace"
       },
       {
         "type": "promptString",
         "id": "surrealdb-db",
         "description": "SurrealDB Database"
       },
       {
         "type": "promptString",
         "id": "surrealdb-user",
         "description": "SurrealDB Username"
       },
       {
         "type": "promptString",
         "id": "surrealdb-pass",
         "description": "SurrealDB Password",
         "password": true
       }
     ],
     "servers": {
       "surrealdb": {
         "type": "stdio",
         "command": "npx",
         "args": [
           "-y",
           "surrealdb-mcp-server"
         ],
         "env": {
           "SURREALDB_URL": "${input:surrealdb-url}",
           "SURREALDB_NS": "${input:surrealdb-ns}",
           "SURREALDB_DB": "${input:surrealdb-db}",
           "SURREALDB_USER": "${input:surrealdb-user}",
           "SURREALDB_PASS": "${input:surrealdb-pass}"
         }
       }
     }
   }
   

   注意： この設定では、VS Code の入力変数を使用して SurrealDB の認証情報を安全に求め、保存します。

2. インストールを確認します：

   • VS Code で GitHub Copilot Chat を開きます
   • ドロップダウンから「Agent」モードを選択します
   • 「Tools」ボタンをクリックして、利用可能なツールを確認します
   • 一覧に SurrealDB のツールが表示されることを確認します

🦘 Roo Code のインストール

VS Code の Roo Code へのインストール

1. MCP 設定にアクセスします：

   Roo Code ペイン上部のナビゲーションにある MCP アイコンをクリックし、「Edit MCP Settings」を選択して設定ファイルを開きます。

2. SurrealDB MCP サーバーの設定を追加します：

   {
     "mcpServers": {
       "surrealdb": {
         "command": "C:\\Program Files\\nodejs\\node.exe",
         "args": [
           "C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\npm\\node_modules\\surrealdb-mcp-server\\build\\index.js"
         ],
         "env": {
           "SURREALDB_URL": "ws://localhost:8000",
           "SURREALDB_NS": "your_namespace",
           "SURREALDB_DB": "your_database",
           "SURREALDB_USER": "your_db_user",
           "SURREALDB_PASS": "your_db_password"
         },
         "disabled": false,
         "autoApprove": []
       }
     }
   }
   

   重要： パス内の YOUR_USERNAME を、実際の Windows ユーザー名に置き換えてください。

3. VS Code を再起動します

4. インストールを確認します：

   • VS Code で Roo Code を開きます
   • MCP アイコンをクリックして、利用可能なサーバーを確認します
   • 一覧に「surrealdb」が表示されることを確認します

🌊 Windsurf のインストール

Windsurf へのインストール

1. パッケージをグローバルにインストールします：

   npm install -g surrealdb-mcp-server
   

2. Windsurf を設定します：

   • システムで Windsurf を開きます
   • 設定ページに移動します
   • Cascade タブを開きます
   • Model Context Protocol（MCP）Servers セクションを見つけます
   • 「View raw config」をクリックして設定ファイルを開きます（通常は ~/.codeium/windsurf/mcp_config.json にあります）

3. SurrealDB MCP サーバーの設定を追加します：

   {
     "servers": [
       {
         "name": "surrealdb",
         "command": "node",
         "args": [
           "/path/to/global/node_modules/surrealdb-mcp-server/build/index.js"
         ],
         "env": {
           "SURREALDB_URL": "ws://localhost:8000",
           "SURREALDB_NS": "your_namespace",
           "SURREALDB_DB": "your_database",
           "SURREALDB_USER": "your_db_user",
           "SURREALDB_PASS": "your_db_password"
         }
       }
     ]
   }
   

   注意： /path/to/global/node_modules を、グローバルの node_modules ディレクトリの実際のパスに置き換えてください。

4. Windsurf を再起動します

5. インストールを確認します：

   • Windsurf で Cascade を開きます
   • ツールの一覧に SurrealDB のツールが表示されることを確認します

⚡ Cursor のインストール

Cursor へのインストール

1. パッケージをグローバルにインストールします：

   npm install -g surrealdb-mcp-server
   

2. Cursor を設定します：

   • Cursor を開きます
   • Settings > Cursor Settings に移動します
   • MCP Servers オプションを見つけ、有効にします
   • 「Add New MCP Server」をクリックします

3. SurrealDB MCP サーバーの設定を追加します：

   {
     "name": "surrealdb",
     "command": "node",
     "args": [
       "/path/to/global/node_modules/surrealdb-mcp-server/build/index.js"
     ],
     "env": {
       "SURREALDB_URL": "ws://localhost:8000",
       "SURREALDB_NS": "your_namespace",
       "SURREALDB_DB": "your_database",
       "SURREALDB_USER": "your_db_user",
       "SURREALDB_PASS": "your_db_password"
     }
   }
   

   注意： /path/to/global/node_modules を、グローバルの node_modules ディレクトリの実際のパスに置き換えてください。

4. Cursor を再起動します

5. インストールを確認します：

   • Cursor Chat を開きます
   • ツールの一覧に SurrealDB のツールが表示されることを確認します

必須環境変数

このサーバーが SurrealDB インスタンスに接続するには、次の環境変数が必要です：

• SURREALDB_URL：SurrealDB インスタンスの WebSocket エンドポイント（例：ws://localhost:8000 または wss://cloud.surrealdb.com）。
• SURREALDB_NS：対象の Namespace。
• SURREALDB_DB：対象の Database。
• SURREALDB_USER：認証に使用するユーザー名（Root、NS、DB、または Scope ユーザー）。
• SURREALDB_PASS：指定したユーザーのパスワード。

トラブルシューティング

よくある問題

「Cannot find module」エラー

「Cannot find module 'surrealdb-mcp-server'」のようなエラーが表示された場合は、次をお試しください。

1. グローバルインストールを確認します：npm list -g surrealdb-mcp-server
2. 設定内のパスが実際のインストール先と一致しているか確認します
3. 再インストールをお試しください：npm install -g surrealdb-mcp-server

接続エラー

「Failed to connect to SurrealDB」と表示された場合は、次をお試しください。

1. SurrealDB が実行中であることを確認します：surreal start --log debug
2. 接続 URL、名前空間、データベース、認証情報を確認します
3. 指定したパスから SurrealDB インスタンスにアクセスできることを確認します

Cline 固有の問題

npx の方法が Cline で動作しない場合は、次をお試しください。

1. Cline では必ずグローバルインストールの方法を使用します
2. node.exe とインストール済みパッケージの完全なパスを指定します
3. YOUR_USERNAME を実際の Windows ユーザー名に置き換えてください

高度な設定

ローカルビルドを使用する

リポジトリをクローンした場合、またはローカルビルドを使用する場合は、次の設定を使用できます。

{
  "mcpServers": {
    "surrealdb": {
      "command": "node",
      "args": ["/path/to/your/surrealdb-mcp-server/build/index.js"],
      "env": {
        "SURREALDB_URL": "ws://localhost:8000",
        "SURREALDB_NS": "your_namespace",
        "SURREALDB_DB": "your_database",
        "SURREALDB_USER": "your_db_user",
        "SURREALDB_PASS": "your_db_password"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

• /path/to/your/surrealdb-mcp-server を、リポジトリをクローンした実際のパスに置き換えます
• 環境変数の値を、実際の SurrealDB 接続情報に置き換えます

開発

この MCP サーバーの開発に貢献する場合は、次の手順に従ってください。

ローカル開発環境のセットアップ

1. リポジトリをクローンします：

   git clone https://github.com/nsxdavid/surrealdb-mcp-server.git
   cd surrealdb-mcp-server
   

2. 依存関係をインストールします：

   npm install
   

3. プロジェクトをビルドします：

   npm run build
   

ローカルでの実行

# Ensure required SURREALDB_* environment variables are set
npm run dev # (Note: dev script uses ts-node to run TypeScript directly)
# Or run the built version:
npm start

テスト

npm test # (Note: Tests need to be implemented)

貢献

皆さまからの貢献を歓迎します。ガイドラインについてはCONTRIBUTING.mdをご覧ください。

n8n との統合

コミュニティノードのn8n-nodes-mcpを使用して、この SurrealDB MCP サーバーをn8nと統合できます。

注：現在、コミュニティノードに対応しているのはn8n のセルフホスト（Docker）版のみです。n8n クラウド版には MCP サーバーのオプションがありません（まだ？）。

インストール

1. n8n-nodes-mcp パッケージをインストールします：

   npm install n8n-nodes-mcp
   

2. カスタムノードを使用するよう n8n を設定します：

   次の内容を n8n の設定に追加します。

   N8N_CUSTOM_EXTENSIONS="n8n-nodes-mcp"
   

3. n8n で MCP ノードを設定します：

   • ワークフローに「MCP」ノードを追加します
   • SurrealDB MCP サーバーに接続するよう設定します
   • 使用する操作（query、select、create など）を選択します
   • 操作パラメーターを設定します

詳細については、n8n-nodes-mcp GitHub リポジトリをご覧ください。

ライセンス

MIT