Supabase MCP Server 🚀

Supabase MCP Server 🚀

🔥 Cursor の Composer と Codeium の Cascade の両方を通じて、Supabase PostgreSQL データベースを完全に管理できる強力な Model Context Protocol（MCP）サーバーです。このツールを使えば、テーブル操作、レコード管理、スキーマ変更など、豊富な機能でデータベースをシームレスに管理できます。

📚 目次

• 前提条件
• クイックスタート
• 連携
• 機能
• 使い方
• セキュリティに関する注意
• トラブルシューティング
• コントリビューション
• ライセンス

🔧 前提条件

• Node.js >= 16.x
• npm >= 8.x
• 以下を備えた Supabase プロジェクト：
  • プロジェクト ID
  • データベースのパスワード
  • PostgreSQL 接続文字列
• Cursor IDE または Codeium の Cascade（有料ユーザー向け）

🚀 クイックスタート

📥 インストール

# Clone the repository
git clone https://github.com/Quegenx/supabase-mcp-server.git
cd supabase-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

⚙️ 設定

1. 依存関係をインストールして、プロジェクトをビルドします。

   npm install
   npm run build
   

2. Cursor の MCP 設定で、次のコマンドを使ってサーバーを追加します。

   /opt/homebrew/bin/node /path/to/dist/index.js postgresql://postgres.[PROJECT-ID]:[PASSWORD]@aws-0-eu-central-1.pooler.supabase.com:5432/postgres
   

   以下を置き換えてください。

   • /path/to/dist/index.js を実際のパスに置き換えます
   • [PROJECT-ID] を Supabase のプロジェクト ID に置き換えます
   • [PASSWORD] をデータベースのパスワードに置き換えます

注意：データベースの認証情報は安全に保管し、バージョン管理に決してコミットしないでください。

🎯 連携

Cursor MCP 連携

Model Context Protocol（MCP）を使用すると、Cursor 内のエージェント型 LLM にカスタムツールを提供できます。このサーバーは Cursor の Composer 機能と連携でき、自然言語のコマンドを使ってすべてのデータベース管理ツールに直接アクセスできます。

Cursor での設定

1. Cursor Settings > Features > MCP を開きます

2. 「+ Add New MCP Server」ボタンをクリックします

3. モーダルフォームに入力します。

   • Name：「Supabase MCP」（または任意の名前）
   • Type：command（stdio トランスポート）
   • Command：接続情報を含むコマンド文字列全体

4. まずプロジェクトをビルドします。

   npm install
   npm run build
   

5. Node.js のパスを確認します。

   # On Mac/Linux
   which node
   # On Windows
   where node
   

6. サーバーコマンドを追加します。

   /path/to/node /path/to/dist/index.js postgresql://postgres.[PROJECT-ID]:[PASSWORD]@aws-0-eu-central-1.pooler.supabase.com:5432/postgres
   

   以下を置き換えてください。

   • /path/to/node を実際の Node.js のパス（手順 5 で確認したもの）に置き換えます
   • /path/to/dist/index.js をビルド済み JavaScript ファイルの実際のパスに置き換えます
   • [PROJECT-ID] を Supabase のプロジェクト ID に置き換えます
   • [PASSWORD] をデータベースのパスワードに置き換えます

7. 「Add Server」をクリックし、右上の更新ボタンをクリックします

Cursor でのツールの使用

Composer エージェントは、データベースのタスクを説明すると、関連するツールを自動的に検出して使用します。例：

• 「データベース内のすべてのテーブルを一覧表示して」
• 「新しい users テーブルを作成して」
• 「email 列にインデックスを追加して」

エージェントがツールを使用すると、次の内容が表示されます。

1. ツール呼び出しを承認または拒否するためのプロンプト
2. ツール呼び出しの引数（展開可能）
3. 承認後の応答

注意：このサーバーのような stdio サーバーでは、有効なシェルコマンドを指定する必要があります。環境変数が必要な場合は、ラッパースクリプトの使用を検討してください。

Windsurf/Cascade との統合

この MCP サーバーは、Codeium の Cascade（Windsurf）との統合にも対応しています。この機能は現在、有料の個人ユーザーのみが利用できます（Teams または Enterprise ユーザーは利用できません）。

Cascade のセットアップ

1. ~/.codeium/windsurf/mcp_config.json を作成または編集します。

   {
     "mcpServers": {
       "supabase-mcp": {
         "command": "/path/to/node",
         "args": [
           "/path/to/dist/index.js",
           "postgresql://postgres.[PROJECT-ID]:[PASSWORD]@aws-0-eu-central-1.pooler.supabase.com:5432/postgres"
         ]
       }
     }
   }
   

2. 設定にすばやくアクセスする方法：

   • Cascade の入力欄の上にあるツールバーを探します
   • ハンマーアイコンをクリックします
   • 「Configure」をクリックして mcp_config.json を開きます

3. 設定内の以下の値を置き換えます：

   • /path/to/node を実際の Node.js のパスに置き換えます
   • /path/to/dist/index.js を実際のパスに置き換えます
   • [PROJECT-ID] を Supabase のプロジェクト ID に置き換えます
   • [PASSWORD] をデータベースのパスワードに置き換えます

4. Cascade で以下を行います：

   • ツールバーのハンマーアイコンをクリックします
   • 「Configure」をクリックして設定を確認します
   • 「Refresh」をクリックして MCP サーバーを読み込みます
   • サーバー名をクリックして利用可能なツールを確認します

Cascade ユーザー向けの重要な注意事項

• ツール機能のみがサポートされています（プロンプトとリソースはサポートされていません）
• MCP ツールの呼び出しは、成功または失敗にかかわらずクレジットを消費します
• 画像出力はサポートされていません
• stdio トランスポートタイプのみがサポートされています
• ツールの呼び出しによって、任意のサーバー実装者が作成したコードが実行される場合があります
• Cascade は MCP ツール呼び出しの失敗について責任を負いません

✨ 機能

🎯 利用可能なデータベースツール

テーブル管理

• テーブル：list_tables、create_table、drop_table、rename_table
• カラム：add_column、drop_column、alter_column
• レコード：fetch_records、create_record、update_record、delete_record

インデックスと制約

• インデックス：list_indexes、create_index、delete_index、update_index
• 制約：list_constraints、add_constraint、remove_constraint、update_constraint

データベース関数とトリガー

• 関数：list_functions、create_function、update_function、delete_function
• トリガー：list_triggers、create_trigger、update_trigger、delete_trigger

セキュリティとアクセス制御

• ポリシー：list_policies、create_policy、update_policy、delete_policy
• ロール：list_roles、create_role、update_role、delete_role

ストレージ管理

• バケット：list_buckets、create_bucket、delete_bucket
• ファイル：delete_file、bulk_delete_files
• フォルダー：list_folders

データ型とパブリケーション

• 列挙型：list_enumerated_types、create_enumerated_type、update_enumerated_type、delete_enumerated_type
• パブリケーション：list_publications、create_publication、update_publication、delete_publication

リアルタイム機能

• ポリシー：list_realtime_policies、create_realtime_policy、update_realtime_policy、delete_realtime_policy
• チャネル：list_realtime_channels、manage_realtime_channels、send_realtime_message、get_realtime_messages
• 管理：manage_realtime_status、manage_realtime_views

ユーザー管理

• 認証：list_users、create_user、update_user、delete_user

SQL への直接アクセス

• クエリ：query - カスタム SQL クエリを実行します

🚀 主なメリット

• 自然言語での操作：簡単な会話形式のコマンドで Supabase データベースを管理できます
• 幅広い機能：テーブル、レコード、インデックス、関数、セキュリティなどを網羅する充実したツール群を利用できます
• シームレスな統合：Cursor の Composer および Codeium の Cascade 内で直接動作します
• 開発者に優しい設計：IDE とデータベース管理ツール間のコンテキスト切り替えを減らします
• 安全なアクセス：適切な認証によってデータベースのセキュリティを維持します

📁 プロジェクト構成

supabase-mcp-server/
├── dist/                    # Compiled JavaScript files
│   ├── index.d.ts          # TypeScript declarations
│   └── index.js            # Main JavaScript file
├── src/                    # Source code
│   └── index.ts           # Main TypeScript file
├── package.json           # Project configuration
├── package-lock.json      # Dependency lock file
└── tsconfig.json         # TypeScript configuration

💡 使い方

設定が完了すると、MCP サーバーは Cursor の Composer を通じてすべてのデータベース管理ツールを提供します。データベースで行いたいことを説明するだけで、AI が適切なコマンドを使用します。

例：

• 📋 「データベース内のすべてのテーブルを表示して」
• ➕ 「id、name、email カラムを持つ users テーブルを新しく作成して」
• 🔍 「users テーブルの email カラムにインデックスを追加して」

🔒 セキュリティに関する注意事項

• 🔐 データベースの接続文字列は安全に保管してください
• ⚠️ 機密性の高い認証情報をバージョン管理にコミットしないでください
• 👮 適切なアクセス制御と権限を設定してください
• 🛡️ SQL インジェクションを防ぐため、すべての入力を検証してサニタイズしてください

🛠️ トラブルシューティング

よくある接続の問題

1. Node.js のパスに関する問題

   • 正しい Node.js のパスを使用していることを確認してください
   • Mac/Linux の場合：which node を使って正しいパスを確認してください
   • Windows の場合：where node を使って正しいパスを確認してください
   • /usr/local/bin/node を実際の Node.js のパスに置き換えてください

2. ファイルパスに関する問題

   • 相対パスではなく絶対パスを使用してください
   • Mac/Linux の場合：プロジェクトディレクトリで pwd を実行してフルパスを取得してください
   • Windows の場合：cd を実行してフルパスを取得してください
   • 例：/Users/username/projects/supabase-mcp-server/dist/index.js

3. MCP がツールを検出しない

   • Cursor の MCP 設定で更新ボタンをクリックしてください
   • サーバーが実行中で、エラーメッセージがないことを確認してください
   • 接続文字列が正しいことを確認してください
   • Supabase の認証情報が有効であることを確認してください

4. 権限に関する問題

   • dist ディレクトリが存在することを確認してください（npm run build を実行してください）
   • ファイルの権限を確認してください（Unix システムでは chmod +x を実行してください）
   • 適切な権限で npm install を実行してください

デバッグモード

詳細なログを表示するには、コマンドの前に DEBUG=true を追加してください：

DEBUG=true /usr/local/bin/node /path/to/dist/index.js [connection-string]

プラットフォーム固有の注意事項

Windows ユーザー

# Use this format for the command
"C:\\Program Files\\nodejs\\node.exe" "C:\\path\\to\\dist\\index.js" "postgresql://..."

Linux ユーザー

# Find Node.js path
which node

# Make script executable
chmod +x /path/to/dist/index.js

問題が解決しない場合は、以下の情報を添えてイシューを作成してください：

• オペレーティングシステム
• Node.js のバージョン（node --version）
• エラーメッセージ全文
• 再現手順

🤝 コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。

📄 ライセンス

---