SurrealDB MCP Server

SurrealDB MCP サーバー

AIアシスタントがSurrealDBデータベースと対話するための標準化されたインターフェースを提供する、モデルコンテキストプロトコル（MCP）サーバー。このサーバーにより、AIシステムは設定されたSurrealDBインスタンス内のデータをクエリおよび操作できるようになります。

**AI アシスタント向けの注意:**このドキュメントを読んでいる AI アシスタント (Claude、Cline、Copilot など) の場合は、ユーザーがこの MCP サーバーをインストールして構成できるように特別に設計された詳細な手順については、 llms-install.mdファイルを参照してください。

インストールガイド

どの AI アシスタントを使用していますか?

• 📝 Cline VS Code拡張機能をお使いですか？ → Clineのインストールへ
• 🖥️ Claudeデスクトップアプリをお使いですか？ → Claudeのインストールへ
• 🤖 VS CodeでGitHub Copilotを使用していますか？ → Copilotのインストールへ
• 🦘 VS Code で Roo Code を使用していますか? → Roo Code のインストールへ
• 🌊 Windsurf をお使いですか？ → Windsurf のインストールへ
• ⚡ カーソルを使用していますか？ →カーソルのインストールへ
• 🔄 n8nをご利用ですか？ → n8n 統合へ

キーワード

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

利用可能なツール

サーバーは、SurrealDB と対話するための次のツールを公開します。

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

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

📝 クライン設置

Cline VS Code拡張機能のワンクリックインストール

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デスクトップアプリのインストール

1. サーバーを使用するように Claude Desktop を構成します。Claude デスクトップ アプリの 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デスクトップアプリを再起動します
3. インストールの確認:
   • クロードに「利用可能な MCP サーバーをリストする」ように依頼します。
   • リストに「surrealdb」が表示されるはずです

🤖 副操縦士のインストール

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チャットを開く
   • ドロップダウンから「エージェント」モードを選択します
   • 利用可能なツールを表示するには、「ツール」ボタンをクリックします
   • リストにSurrealDBツールが表示されるはずです

🦘 Roo Codeのインストール

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

1. MCP 設定にアクセスします。Roo Code ペインの上部ナビゲーションにある MCP アイコンをクリックし、「MCP 設定の編集」を選択して構成ファイルを開きます。
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」が表示されるはずです

🌊 ウィンドサーフィンの設置

ウィンドサーフィン用インスタレーション

1. パッケージをグローバルにインストールします。
   npm install -g surrealdb-mcp-server
2. Windsurf の設定:
   • システムでWindsurfを開きます
   • 設定ページに移動します
   • カスケードタブへ移動
   • モデルコンテキストプロトコル（MCP）サーバーセクションを見つけます
   • 「生の構成を表示」をクリックして構成ファイルを開きます（通常は~/.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. ウィンドサーフィンを再開
5. インストールの確認:
   • ウィンドサーフィンのオープンカスケード
   • ツールリストにSurrealDBツールが表示されるはずです。

⚡ カーソルのインストール

カーソルのインストール

1. パッケージをグローバルにインストールします。
   npm install -g surrealdb-mcp-server
2. カーソルの設定:
   • オープンカーソル
   • 設定 > カーソル設定に移動します
   • MCPサーバーオプションを見つけて有効にします
   • 「新しいMCPサーバーを追加」をクリックします
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. カーソルを再開
5. インストールの確認:
   • カーソルチャットを開く
   • ツールリストにSurrealDBツールが表示されるはずです。

必要な環境変数

このサーバーは、SurrealDB インスタンスに接続するために次の環境変数を必要とします。

• SURREALDB_URL : SurrealDB インスタンスの WebSocket エンドポイント (例: ws://localhost:8000またはwss://cloud.surrealdb.com )。
• SURREALDB_NS : ターゲット名前空間。
• SURREALDB_DB : ターゲット データベース。
• SURREALDB_USER : 認証用のユーザー名 (ルート、NS、DB、またはスコープ ユーザー)。
• SURREALDB_PASS : 指定されたユーザーのパスワード。

トラブルシューティング

よくある問題

「モジュールが見つかりません」エラー

「モジュール 'surrealdb-mcp-server' が見つかりません」のようなエラーが表示された場合は、次の操作を試してください。

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

接続エラー

「SurrealDB への接続に失敗しました」と表示された場合:

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

クライン特有の問題

npx アプローチが Cline で機能しない場合は、次の手順に従ってください。

1. Clineには常にグローバルインストール方法を使用してください
2. node.exeとインストールされたパッケージへのフルパスを指定します
3. YOUR_USERNAMEを実際のWindowsユーザー名に置き換えてください。

詳細設定

ローカルビルドの使用

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

• /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

ローカルで実行

テスト

貢献

貢献を歓迎します！ガイドラインについては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サーバーに接続するように設定します
   • 必要な操作 (クエリ、選択、作成など) を選択します。
   • 操作パラメータを設定する

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

ライセンス

マサチューセッツ工科大学