Supabase MCP Server

Supabase MCP サーバー

CursorとWindsurfがSupabaseデータベースと安全にやり取りできるようにする、機能豊富なMCPサーバーです。データベース管理、SQLクエリ実行、そしてSupabase管理APIアクセスのためのツールを提供し、安全管理機能が組み込まれています。

目次

✨ 主な機能

• 💻 Cursor、Windsurf、Cline、その他stdioプロトコルをサポートするMCPクライアントと互換性があります
• 🔐 SQLクエリ実行の読み取り専用モードと読み取り/書き込みモードを制御する
• 🔄 直接接続とプールされたデータベース接続の両方に対する堅牢なトランザクション処理
• 💻 Supabase管理APIでSupabaseプロジェクトを管理する
• 🧑‍💻 Python SDK 経由で Supabase Auth Admin メソッドを使用してユーザーを管理する
• 🔨 Cursor と Windsurf が MCP とより効果的に連携できるようにするための事前構築済みツール
• 📦 パッケージ マネージャー (uv、pipx など) による非常に簡単なインストールとセットアップ

はじめる

前提条件

サーバーをインストールするには、システムに次のものが必要です。

• Python 3.12以上
• PostgreSQL 16以上

uv経由でインストールする予定の場合は、それがインストールされていることを確認してください。

PostgreSQLのインストール

⚠️重要: psycopg2 はコンパイル時に PostgreSQL 開発ライブラリを必要とするため、プロジェクトの依存関係をインストールする前に PostgreSQL をインストールする必要があります。

macOS

ウィンドウズ

• https://www.postgresql.org/download/windows/から PostgreSQL 16 以降をダウンロードしてインストールします。
• インストール中に「PostgreSQLサーバー」と「コマンドラインツール」が選択されていることを確認してください。

ステップ1. MCPサーバーのインストール

v0.2.0以降、パッケージインストールのサポートを導入しました。お好みのPythonパッケージマネージャーを使って、以下のコマンドでサーバーをインストールできます。

pipxパッケージごとに分離された環境を作成するため推奨されます。

リポジトリのクローンを作成し、ルート ディレクトリからpipx install -editable . を実行して、サーバーを手動でインストールすることもできます。

⚠️ psycopg2 のコンパイルで問題が発生する場合は、PostgreSQL 開発パッケージが不足している可能性があります。上記を参照してください。

ソースからインストールする

たとえばローカル開発のためにソースからインストールする場合:

Smithery.ai経由でインストール

Smithery についてはまだテストしていないので、問題があれば報告してください。

Smithery経由で Claude Desktop 用の Supabase MCP Server を自動的にインストールするには:

ステップ2. 構成

パッケージをインストールしたら、データベース接続設定を行う必要があります。サーバーはローカルとリモートの両方のSupabaseインスタンスをサポートしています。

ローカル Supabase インスタンス (デフォルト)

サーバーは、デフォルト設定を使用してローカル Supabase インスタンスに接続するように事前構成されています。

• Host : 127.0.0.1:54322
• Password : postgres

💡 デフォルト設定を変更せず、ローカルインスタンスに接続する場合は、環境変数を設定する必要はありません。

リモート Supabase インスタンス

⚠️重要なお知らせ：セッションプーリング接続はサポートされておらず、現時点ではサポートする予定もありません。MCPサーバーでこれをサポートするユースケースがあると思われる場合はお知らせください。

リモート Supabase プロジェクトの場合は、以下を構成する必要があります。

• SUPABASE_PROJECT_REF - プロジェクト参照（プロジェクト URL に記載）
• SUPABASE_DB_PASSWORD - データベースのパスワード
• SUPABASE_REGION - (オプション) デフォルトはus-east-1
• SUPABASE_ACCESS_TOKEN - (オプション) 管理APIアクセス用

プロジェクトのダッシュボード URL から SUPABASE_PROJECT_REF を取得できます。

• https://supabase.com/dashboard/project/<supabase-project-ref>

サーバーはすべての Supabase リージョンをサポートします。

• us-west-1 - 米国西部（北カリフォルニア）
• us-east-1 - 米国東部（バージニア州北部） - デフォルト
• us-east-2 - 米国東部（オハイオ州）
• ca-central-1 - カナダ（中部）
• eu-west-1 - 西EU（アイルランド）
• eu-west-2 - 西ヨーロッパ（ロンドン）
• eu-west-3 - 西EU（パリ）
• eu-central-1 - 中央 EU (フランクフルト)
• eu-central-2 - 中央ヨーロッパ（チューリッヒ）
• eu-north-1 - 北EU（ストックホルム）
• ap-south-1 - 南アジア（ムンバイ）
• ap-southeast-1 - 東南アジア（シンガポール）
• ap-northeast-1 - 北東アジア（東京）
• ap-northeast-2 - 北東アジア（ソウル）
• ap-southeast-2 - オセアニア（シドニー）
• sa-east-1 - 南アメリカ (サンパウロ)

MCPの設定方法は、CursorとWindsurfで異なります。接続の設定方法については、該当するセクションをお読みください。

カーソル

v0.46 以降、Cursor で MCP サーバーを構成する方法は 2 つあります。

• プロジェクトごとに -> プロジェクト/リポジトリフォルダにmcp.jsonを作成し、接続を構成するための.env作成します。
• グローバル -> 設定で MCP サーバーを作成し、この MCP サーバーでのみサポートされている.envを使用して構成します。

プロジェクト固有の MCP は次の方法で作成できます。

• リポジトリに.cursorフォルダが存在しない場合は作成します
• 以下の設定でmcp.jsonファイルを作成または更新する

⚠環境変数: プロジェクトごとにMCPサーバーを設定する場合でも、接続設定を取得するために.envファイルを作成する必要があります。私の場合、mcp.jsonで環境変数を取得できませんでした😔

あるいは、MCP サーバーをグローバルに (つまり、プロジェクトごとにではなく) 構成する場合は、次のコマンドを実行してグローバル構成フォルダー内の.envファイルを更新することにより、接続設定を構成できます。

これにより、環境ファイルが保存される必要な config フォルダーが作成されます。

.envファイルが開きます。ファイルが開いたら、以下の内容をコピー＆ペーストしてください。

ファイルが存在することを確認します。設定した値が表示されます。

グローバル設定ファイルは次の場所にあります:

• Windows: %APPDATA%/supabase-mcp/.env
• macOS/Linux: ~/.config/supabase-mcp/.env

ウィンドサーフィン

Windsurfは、MCPサーバーの設定に事実上の標準である.json形式をサポートしています。サーバーの設定はmcp_config.jsonファイルで行うことができます。

💡サーバーパスを見つける:

• macOS/Linux: which supabase-mcp-serverを実行する
• Windows: where supabase-mcp-serverを実行します。

構成の優先順位

サーバーは次の順序で構成を検索します。

1. 環境変数（最優先）
2. 現在のディレクトリにあるローカル.envファイル
3. グローバル設定ファイル:
   • Windows: %APPDATA%/supabase-mcp/.env
   • macOS/Linux: ~/.config/supabase-mcp/.env
4. デフォルト設定（ローカル開発）

ステップ3. Cursor/WindsurfでMCPサーバーを実行する

一般に、 stdioプロトコルをサポートする MCP クライアントは、この MCP サーバー (たとえば、Cline) で動作するはずですが、Cursor/Windsurf 以外ではテストしていません。

カーソル

[設定] -> [機能] -> [MCP サーバー] に移動し、次の構成で新しいサーバーを追加します。

構成が正しい場合は、緑色のドットのインジケーターと、サーバーによって公開されているツールの数が表示されます。

ウィンドサーフィン

Cascade に移動 -> ハンマーアイコンをクリック -> 構成 -> 構成を入力します。

設定が正しい場合、利用可能なサーバーのリストに緑色のドット インジケーターとクリック可能な supabase サーバーが表示されます。

トラブルシューティング

役立つヒントとコツをいくつか紹介します。

• デバッグインストール- ターミナルからsupabase-mcp-serverを直接実行して、動作するかどうかを確認してください。動作しない場合は、インストールに問題がある可能性があります。
• MCPサーバーの設定- 上記の手順がうまくいけば、サーバーは正しくインストールされ、設定されていることを意味します。正しいコマンドを入力していれば、IDEから接続できるはずです。サーバーの実行ファイルへの正しいパスを指定してください。
• 環境変数- 適切なデータベースに接続するには、 mcp_config.jsonまたはグローバル構成ディレクトリ (macOS/Linux の場合は~/.config/supabase-mcp/.env``.env Windows の場合は%APPDATA%\supabase-mcp\.env ) に配置された .env ファイルで環境変数を設定してください。
• ログへのアクセス- MCP サーバーは詳細なログをファイルに書き込みます。
  • ログファイルの場所:
    • macOS/Linux: ~/.local/share/supabase-mcp/mcp_server.log
    • Windows: %USERPROFILE%\.local\share\supabase-mcp\mcp_server.log
  • ログには接続ステータス、構成の詳細、操作結果が含まれます
  • 任意のテキスト エディターまたはターミナル コマンドを使用してログを表示します。
    # On macOS/Linux cat ~/.local/share/supabase-mcp/mcp_server.log # On Windows (PowerShell) Get-Content "$env:USERPROFILE\.local\share\supabase-mcp\mcp_server.log"

行き詰まったり、上記の手順のいずれかが間違っていたりする場合は、問題を報告してください。

MCP検査官

MCPサーバーの問題をデバッグするのに非常に便利なツールがMCP Inspectorです。ソースコードからインストールした場合は、プロジェクトリポジトリからsupabase-mcp-inspector実行すると、インスペクターインスタンスが実行されます。ログと組み合わせることで、サーバーで何が起こっているかを完全に把握できます。

📝 パッケージからインストールされた場合、 supabase-mcp-inspector実行は正常に動作しません。今後のリリースで検証して修正します。

機能の概要

データベースクエリツール

v0.3.0 以降、サーバーは読み取り専用操作とデータ変更操作の両方をサポートします。

• 読み取り操作: データ取得のためのSELECTクエリ
• データ操作言語 (DML) : データ変更のための INSERT、UPDATE、DELETE 操作
• データ定義言語 (DDL) : スキーマ変更のための CREATE、ALTER、DROP 操作*

*注: DDL 操作には次のものが必要です。

1. live_dangerouslyで読み書きモードが有効になりました
2. 接続されたデータベースロールに対する十分な権限

トランザクション処理

サーバーは書き込み操作を実行するための 2 つの方法をサポートしています。

1. 明示的なトランザクション制御（推奨）:
   BEGIN; CREATE TABLE public.test_table (id SERIAL PRIMARY KEY, name TEXT); COMMIT;
2. 単一のステートメント:
   CREATE TABLE public.test_table (id SERIAL PRIMARY KEY, name TEXT);

DDL 操作 (CREATE/ALTER/DROP) の場合、ツールの説明は、Cursor/Windsurft が BEGIN/COMMIT ブロックを使用して明示的なトランザクション制御を使用するように適切にガイドします。

接続タイプ

この MCP サーバーは以下を使用します:

• 直接データベース接続: ローカルの Supabase インスタンスに接続する場合
• トランザクションプーラー接続: リモート Supabase インスタンスに接続する場合

Supabaseのトランザクションプーラー経由で接続する場合、一部の複雑なトランザクションパターンは期待どおりに動作しない可能性があります。このような環境でスキーマを変更する場合は、明示的なトランザクションブロックを使用するか、SupabaseのマイグレーションまたはダッシュボードのSQLエディターの使用を検討してください。

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

• get_db_schemas - すべてのデータベーススキーマとそのサイズおよびテーブル数を一覧表示します
• get_tables - スキーマ内のすべてのテーブルを、そのサイズ、行数、メタデータとともに一覧表示します。
• get_table_schema - 列、キー、関係を含む詳細なテーブル構造を取得します
• execute_sql_query - すべての PostgreSQL 操作を包括的にサポートして生の SQL クエリを実行します。
  • すべてのクエリ タイプ (SELECT、INSERT、UPDATE、DELETE、CREATE、ALTER、DROP など) をサポートします
  • トランザクション制御文（BEGIN、COMMIT、ROLLBACK）を処理します
• サポートされているモード:
  • read-only - 読み取り専用クエリのみが許可されます（デフォルトモード）
  • read-write - 明示的に有効にするとすべてのSQL操作が許可されます
• 安全機能:
  • デフォルトでは読み取り専用モードで起動します
  • 書き込み操作には明示的なモード切り替えが必要
  • 書き込み操作後に自動的に読み取り専用モードにリセットされます
  • エラーを防ぐためのインテリジェントなトランザクション状態検出
  • SQLクエリの検証 [TODO]

管理APIツール

v0.3.0 以降、サーバーはプロジェクト参照の自動挿入と安全モード制御を使用して、Supabase 管理 API への任意のリクエストの送信をサポートします。

• 次のツールが含まれています:
  • プロジェクト参照の自動挿入と安全モード制御を使用して、任意のリクエストを Supabase Management API に送信するためのsend_management_api_request
  • get_management_api_spec 、安全性情報を含む充実した API 仕様を取得します。
  • get_management_api_safety_rules 、ブロックされた操作や安全でない操作を含むすべての安全ルールを人間が読める説明とともに取得します。
  • 安全モードと非安全モードを切り替えるにはlive_dangerously使用します
• 安全機能:
  • 操作のリスクに基づいて、API メソッドをsafe 、 unsafe 、 blockedカテゴリに分類します。
  • 安全モードと非安全モードを動的に切り替えることができます
  • ブロックされた操作（プロジェクトの削除��データベースの削除）は、モードに関係なく許可されません。

認証管理ツール

MCPサーバーにPython SDKメソッドのサポートを追加する予定でした。検討の結果、テストユーザーを手動で作成することが多く、エラーが発生しやすく、時間がかかるため、Auth Adminメソッドのサポートのみを追加することにしました。これで、Cursorにテストユーザーの作成を依頼するだけで、シームレスに処理されます。Auth Admin SDKメソッドの機能について詳しくは、完全なドキュメントをご覧ください。

v0.3.6 以降、サーバーは Python SDK 経由で Supabase Auth Admin メソッドへの直接アクセスをサポートしています。

• 次のツールが含まれています:
  • get_auth_admin_methods_spec 、利用可能なすべての Auth Admin メソッドのドキュメントを取得します。
  • call_auth_admin_method 、適切なパラメータ処理を使用して Auth Admin メソッドを直接呼び出します。
• サポートされているメソッド:
  • get_user_by_id : IDでユーザーを取得する
  • list_users : ページ区切りですべてのユーザーを一覧表示する
  • create_user : 新しいユーザーを作成する
  • delete_user : IDでユーザーを削除する
  • invite_user_by_email : ユーザーのメールアドレスに招待リンクを送信する
  • generate_link : さまざまな認証目的でメールリンクを生成する
  • update_user_by_id : IDでユーザー属性を更新する
  • delete_factor : ユーザーの要素を削除します (現在 SDK では実装されていません)

生の SQL クエリの代わりに Auth Admin SDK を使用する理由は何ですか?

Auth Admin SDK には、直接 SQL を操作する場合に比べていくつかの重要な利点があります。

• 機能: SQL だけでは不可能な操作 (招待、マジックリンク、MFA) を有効にします
• 精度: 認証スキーマで生のSQLクエリを作成して実行するよりも信頼性が高い
• シンプルさ: 適切な検証とエラー処理を備えた明確な方法を提供します
  • 応答形式:
    • すべてのメソッドは生の辞書ではなく構造化されたPythonオブジェクトを返します
    • オブジェクト属性にはドット表記を使用してアクセスできます（例： user["id"]ではなくuser.id ）
  • エッジケースと制限:
    • UUID検証: 多くのメソッドでは、ユーザーIDに有効なUUID形式が必要であり、特定の検証エラーが返されます。
    • メール設定: invite_user_by_emailやgenerate_linkのようなメソッドでは、Supabaseプロジェクトでメール送信を設定する必要があります。
    • リンク タイプ: リンクを生成する場合、リンク タイプごとに要件が異なります。
      • signupリンクはユーザーの存在を必要としない
      • magiclinkとrecoveryリンクでは、ユーザーがすでにシステムに存在している必要があります。
    • エラー処理: サーバーはSupabase APIからの詳細なエラーメッセージを提供しますが、ダッシュボードインターフェースとは異なる場合があります。
    • メソッドの可用性: delete_factorなどの一部のメソッドは API で公開されていますが、SDK では完全に実装されていません。

ロードマップ

• 📦 パッケージマネージャーによるインストールの簡素化 - ✅ (v0.2.0)
• 🌎 さまざまな Supabase リージョンのサポート - ✅ (v0.2.2)
• 🎮 安全制御を備えた Supabase 管理 API へのプログラムによるアクセス - ✅ (v0.3.0)
• 👷‍♂️ 安全制御を備えたデータベース SQL クエリの読み取りと読み取り/書き込み - ✅ (v0.3.0)
• 🔄 直接接続とプール接続の両方に対する堅牢なトランザクション処理 - ✅ (v0.3.2)
• 🐍 ネイティブ Python SDK で利用可能なメソッドとオブジェクトをサポート - ✅ (v0.3.6)
• 🔍 より強力な SQL クエリ検証 (読み取り操作と書き込み操作)
• 📝 DDL クエリの自動バージョン管理(?)
• 🪵 データベース、エッジ機能のログに簡単にアクセスするためのツール / リソース (?)
• 👨‍💻 Supabase CLI 統合 (?)

Supabaseログに接続する

デバッグに役立つ可能性のある Supabase db ログに接続できるかどうかを調査する予定です (まだサポートされていない場合)。

お楽しみください！☺️