Claude CodeとSupabase MCPの接続方法｜read-only設定・SQL・認証を解説

Claude CodeとSupabase MCPを接続すると、データベースの構造やログを確認しながら、コードとの不整合を調べられます。この記事では、対象プロジェクトを指定した接続、認証、読み取り専用設定を順番に解説します。

SQLやマイグレーション、Edge Functionsを扱う場合は、接続先と操作範囲の確認が重要です。設定コマンドだけでなく、接続後の確認方法と、つながらない場合の調べ方も整理しました。

Supabase MCPとは？

Supabase MCPは、AIツールとSupabaseをModel Context Protocolで接続する公式サーバーです。利用可能なツールを通じて、プロジェクトのデータベースや関連情報を扱います。

ホスト型の基本エンドポイントは次のURLです。

https://mcp.supabase.com/mcp

Claude Codeへ接続すれば、手元のコードと実際のDB構造を照合できます。ただし、アプリ利用者の権限で動く接続とは異なります。開発者向けの接続として管理してください。

Claude CodeとSupabase MCPの接続方法

1．対象プロジェクトを確認する

Supabase Dashboardで、接続したいプロジェクトの参照IDを確認します。以下のYOUR_PROJECT_REFを実際の値へ置き換えてください。

初回の調査向けに、プロジェクト指定・読み取り専用クエリ・必要なツール群を組み合わせた例です。

claude mcp add --scope local --transport http supabase "https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REF&read_only=true&features=database,debugging,development,docs"

URLは、&をシェルに解釈させないよう引用符で囲みます。すでに同じ名前で登録している場合は、重複追加せず既存設定を確認してください。

2．ブラウザで認証する

Claude Code内で次のメニューを開き、supabaseを選んで認証を進めます。

/mcp

ブラウザでは、対象プロジェクトが所属するOrganizationへのアクセスを確認します。通常のホスト型接続では、Personal Access Tokenを手動発行せず認証できます。

3．接続と対象を確認する

claude mcp list
claude mcp get supabase

登録状態を確認したら、対象を限定して最初の調査を依頼します。

接続先のプロジェクトを確認してください。
公開されているMCPツールを使い、
publicスキーマのテーブル構造を調べてください。

顧客データの本文や秘密情報は取得せず、
テーブル名とカラム構成を報告してください。
変更操作は行わないでください。

これは作業範囲を伝える例です。読み取り制限そのものは、接続設定と認証権限でも確認します。

重要：2種類の「project scope」は別

共有する.mcp.jsonには、アクセストークンなどの秘密値を直接保存しないようにします。

read_only・project_ref・featuresの違い

これらは認証権限の代わりではありません。接続URL、サービス上の権限、実際に利用可能なツールを合わせて確認します。

特にread_onlyを「すべての管理操作を一律に禁止する設定」とだけ理解しないことが重要です。読み取り可能なデータにも機密情報が含まれる場合があります。

Supabase MCPでできること

以下は公式に案内されている主な機能です。利用可否は、有効なツール群、認証権限、接続モードによって変わります。

SQL・マイグレーションを扱う流れ

DB変更では、現在の状態を確認してから差分を作り、検証後に適用する流れが重要です。

読み取り専用接続で調査した後、書き込みが必要になった場合は、接続対象と権限を改めて確認します。SQLが生成されたことと、適用してよいことは別です。

ログ調査とTypeScript型生成

現在の公式ツール一覧では、ログをSQLで絞り込み・集計するquery_logsが案内されています。対象期間やサービスを指定し、必要な範囲を調べましょう。

型生成は、DBスキーマとコード側の型を揃える用途に役立ちます。ただし、生成した型をファイルへ反映し、アプリで確認する作業は別途必要です。

本番DBへ接続してもよい？

現在のSupabase公式は、本番の証拠が必要な作業に限って接続し、プロジェクト指定、読み取り専用、ツール群の制限、必要最小限のクエリを使う方針を示しています。

旧稿の「本番へ接続しないことを一律に推奨」という説明を、この方針へ更新しました。通常の実装や変更テストは、開発環境で行う構成が適しています。

最新情報：確認ダイアログは追加の仕組み

公式には、費用が発生するリソース作成や、破壊的と判定されたSQLについて、MCPのElicitationを使う確認フローも案内されています。

ただし、サーバーとクライアントの対応状況に左右され、すべての危険な操作を検出する保証ではありません。ダイアログが出ないことを、安全なSQLの証明とは扱わないようにします。

Edge Functionの秘密値を設定する対応フローでは、値をSupabase Dashboardへ入力します。秘密値をチャットやMCP引数へ渡す運用とは区別してください。

ローカルSupabaseに接続する場合

Supabase CLIの標準的なローカル構成では、次のMCP URLが案内されています。

http://localhost:54321/mcp

ただし、複数プロジェクトや実験的なstack設定ではポートが異なる場合があります。次の出力に表示された接続先を確認してください。

supabase status

別の端末やコンテナでClaude Codeを使う場合、localhostが指す環境も変わります。

Supabase MCPに接続できないときの確認点

ツールを使えない理由を確認する前に、対象制限や読み取り制限をすべて外す方法は避けましょう。まず必要な操作と不足している権限を特定します。

OAuthとPersonal Access Tokenの違い

通常の対話利用はブラウザ認証が基本です。一方、ブラウザ認証が難しいCIなどではPATを使う構成も公式に案内されています。

現在のPATには、対象Organization・Projectと権限を絞る仕組みがあります。トークンを使う場合も、アカウント全体の権限を渡す必要があるとは限りません。

認証情報は実行環境の秘密情報管理で扱い、リポジトリや記事へ貼り付けないようにします。

Supabase Pluginとの違い

Supabase Pluginは、MCPとAgent Skillsをまとめた導入パッケージです。旧稿の「Pluginは知識だけ」という理解では不十分です。

Pluginと手動設定を併用する場合は、同じ接続が重複していないか確認してください。どちらも、導入しただけで最終的なアクセス範囲を確認しなくてよいわけではありません。

よくある質問

read-onlyなら機密情報も安全？

書き込み制限と、情報を読める範囲は別です。必要なデータだけを取得し、結果の転記先も確認します。

–scope projectでSupabaseを1つに絞れる？

絞れません。これはClaude Code設定の共有範囲です。Supabase側の対象指定にはproject_refを使います。

必ずPATを発行する必要がある？

通常のホスト型接続では不要です。CIなど、利用環境に応じて別の認証方式を選びます。

MCPで確認できれば、アプリのRLSも正常？

それだけでは判断できません。開発者の接続とアプリ利用者の権限は異なるため、実際のユーザー権限でアクセスを検証する必要があります。

OmochiXの見解：DBとコードの対応を確認できることが価値

OmochiX編集部の見解

Supabase MCPは、現在のDBやログを根拠にコードを調べる手段として役立ちます。SQLを生成する速さだけでなく、対象を間違えず、変更の影響を確認できる運用が重要だと考えます。

Vercelやブラウザツールを組み合わせる場合も、フロントエンドのPreviewがどのDBを使っているかを確認しましょう。別環境の情報を照合すると、誤った修正につながる可能性があります。

まとめ

Claude CodeとSupabase MCPの接続では、対象Projectを指定して認証し、必要なツールとアクセスを確認します。特に設定スコープとproject_refは混同しないようにしましょう。

まずは構造やログの調査から始め、変更は開発環境で検証します。接続先、権限、確認結果を残せる構成が、継続して使いやすい開発環境につながります。

関連記事