Supabase MCP Server

Supabase MCP サーバー

Claude やその他の LLM が Supabase と連携し、Postgres テーブルに対する CRUD 操作を実行できる Model Context Protocol（MCP）サーバーです。

機能

• データベース操作：
  • フィルターを使ったデータのクエリ
  • データの挿入
  • データの更新
  • データの削除
  • テーブルの一覧表示

前提条件

• Node.js（v16 以降）
• npm または yarn
• API キーを設定した Supabase プロジェクト

インストール

オプション 1：npm からインストール（推奨）

パッケージは npm で公開されています。次のコマンドでグローバルにインストールできます。

npm install -g supabase-mcp

または、プロジェクト内にローカルインストールします。

npm install supabase-mcp

オプション 2：リポジトリをクローン

git clone https://github.com/Cappahccino/SB-MCP.git
cd SB-MCP
npm install
npm run build

設定

Supabase の認証情報を記載した .env ファイルを作成します。

# Supabase credentials
SUPABASE_URL=your_supabase_project_url
SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key

# MCP server configuration
MCP_SERVER_PORT=3000
MCP_SERVER_HOST=localhost
MCP_API_KEY=your_secret_api_key

Claude での使用

互換性を保つため、Claude では特定のトランスポートモードが必要です。このパッケージには、Claude との連携に特化したバイナリが用意されています。

Claude Desktop MCP 設定

"supabase": {
  "command": "npx",
  "args": [
    "-y",
    "supabase-mcp@latest",
    "supabase-mcp-claude"
  ],
  "env": {
    "SUPABASE_URL": "your_supabase_project_url",
    "SUPABASE_ANON_KEY": "your_supabase_anon_key", 
    "SUPABASE_SERVICE_ROLE_KEY": "your_service_role_key",
    "MCP_API_KEY": "your_secret_api_key"
  }
}

設定で必要な環境変数を指定してください。Claude は通信に stdio トランスポートを使用します。

Claude 用バイナリでの手動テスト

Claude 以外の環境でテストするには、次のコマンドを実行します。

npm run start:claude

グローバルにインストールしている場合は、次のコマンドを実行します。

supabase-mcp-claude

スタンドアロンサーバーとしての使用

グローバルにインストールした後、次のコマンドを実行します。

supabase-mcp

これにより、http://localhost:3000（または .env ファイルで指定したポート）で MCP サーバーが起動します。

コード内での使用

supabase-mcp は、独自の Node.js プロジェクトでライブラリとして使用することもできます。

import { createServer, mcpConfig, validateConfig } from 'supabase-mcp';

// Validate configuration
validateConfig();

// Create the server
const app = createServer();

// Start the server
app.listen(mcpConfig.port, mcpConfig.host, () => {
  console.log(`Supabase MCP server running at http://${mcpConfig.host}:${mcpConfig.port}`);
});

トラブルシューティング

よくある問題と解決方法

1. 「ポート XXXX はすでに使用されています」

HTTP サーバーは、利用可能なポートを自動的に検索します。.env ファイルの MCP_SERVER_PORT の値を変更して、別のポートを手動で指定できます。

2. 「必須の環境変数がありません」

必要な値をすべて設定した適切な .env ファイルがあること、またはシステムで環境変数を設定していることを確認してください。

3. 「TypeError: Class constructor Server cannot be invoked without 'new'」

このエラーが表示される場合は、パッケージの古いバージョンを実行している可能性があります。最新バージョンに更新してください。

npm install -g supabase-mcp@latest

4. Claude での JSON 解析エラー

通常の HTTP サーバー（supabase-mcp）ではなく、Claude 専用バイナリ（supabase-mcp-claude）を使用していることを確認してください。

5. Claude でリクエストがタイムアウトする

通常、Claude が接続を開始したものの、サーバーが時間内に応答できなかったことを意味します。以下を確認してください。

• Supabase の認証情報は正しいですか？
• サーバーは適切に設定され、稼働していますか？
• 接続を妨げているものはありませんか？

ツールのリファレンス

データベースツール

1. queryDatabase

   • パラメーター：
     • table（string）：クエリ対象のテーブル名
     • select（string、省略可）：カンマ区切りの列名リスト（デフォルト：「*」）
     • query（object、省略可）：フィルター条件

2. insertData

   • パラメーター：
     • table（string）：テーブル名
     • data（object または object の配列）：挿入するデータ

3. updateData

   • パラメーター：
     • table（string）：テーブル名
     • data（object）：キーと値のペアとして指定する更新データ
     • query（object）：更新対象のフィルター条件

4. deleteData

   • パラメーター：
     • table（string）：テーブル名
     • query（object）：削除対象のフィルター条件

5. listTables

   • パラメーター：なし

バージョン履歴

• 1.0.0：初回リリース
• 1.0.1：ポートの自動選択を追加
• 1.0.2：プロトコルの互換性に関する問題を修正
• 1.0.3：JSON-RPC サポートを追加
• 1.1.0：公式 MCP SDK を使用して全面的に書き換え
• 1.2.0：Claude 用の個別トランスポートを追加し、ポートの競合に関する問題を修正
• 1.3.0：TypeScript プロジェクトとの互換性を向上するために更新
• 1.4.0：Supabase コミュニティのベストプラクティスに基づき、Claude の stdio トランスポート連携を修正
• 1.5.0：安定性の向上とデータベース操作への注力のため、Edge Function のサポートを削除

ライセンス

MIT