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拡張機能のワンクリックインストール

パッケージをグローバルにインストールします。
npm install -g surrealdb-mcp-server
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 ユーザー名に置き換えてください。
VS Codeを再起動する
インストールの確認:
- VS CodeでClineを開く
- Cline に「利用可能な MCP サーバーを一覧表示する」ように依頼します。
- リストに「surrealdb」が表示されるはずです

🖥️ クロード・インスタレーション

Claudeデスクトップアプリのインストール

サーバーを使用するように 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からパッケージを自動的にダウンロードして実行します。手動でインストールする必要はありません。
Claudeデスクトップアプリを再起動します
インストールの確認:
- クロードに「利用可能な MCP サーバーをリストする」ように依頼します。
- リストに「surrealdb」が表示されるはずです

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

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

ワークスペース構成ファイルを作成します。ワークスペースに.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 資格情報を安全に要求し、保存します。
インストールの確認:
- VS CodeでGitHub Copilotチャットを開く
- ドロップダウンから「エージェント」モードを選択します
- 利用可能なツールを表示するには、「ツール」ボタンをクリックします
- リストにSurrealDBツールが表示されるはずです

🦘 Roo Codeのインストール

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

MCP 設定にアクセスします。Roo Code ペインの上部ナビゲーションにある MCP アイコンをクリックし、「MCP 設定の編集」を選択して構成ファイルを開きます。
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 ユーザー名に置き換えてください。
VS Codeを再起動する
インストールの確認:
- VS CodeでRoo Codeを開く
- 利用可能なサーバーを確認するには、MCPアイコンをクリックしてください。
- リストに「surrealdb」が表示されるはずです

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

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

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

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

カーソルのインストール

パッケージをグローバルにインストールします。
npm install -g surrealdb-mcp-server
カーソルの設定:
- オープンカーソル
- 設定 > カーソル設定に移動します
- MCPサーバーオプションを見つけて有効にします
- 「新しいMCPサーバーを追加」をクリックします
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 ディレクトリへの実際のパスに置き換えます。
カーソルを再開
インストールの確認:
- カーソルチャットを開く
- ツールリストに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' が見つかりません」のようなエラーが表示された場合は、次の操作を試してください。

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

接続エラー

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

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

クライン特有の問題

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

Clineには常にグローバルインストール方法を使用してください
node.exeとインストールされたパッケージへのフルパスを指定します
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 サーバーの開発に貢献したい場合は、次の手順に従ってください。

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

リポジトリをクローンします。
git clone https://github.com/nsxdavid/surrealdb-mcp-server.git cd surrealdb-mcp-server
依存関係をインストールします:
npm install
プロジェクトをビルドします。
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サーバーのオプションは（今のところ？）ありません。

インストール

n8n-nodes-mcp パッケージをインストールします。
npm install n8n-nodes-mcp
カスタムノードを使用するように n8n を構成します。n8n 構成に以下を追加します。
N8N_CUSTOM_EXTENSIONS="n8n-nodes-mcp"
n8n で MCP ノードを構成します。
- ワークフローに「MCP」ノードを追加します
- SurrealDB MCPサーバーに接続するように設定します
- 必要な操作 (クエリ、選択、作成など) を選択します。
- 操作パラメータを設定する

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

ライセンス

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

SurrealDB MCP Server