Claude × Supabase MCP の使い方｜接続手順と read-only 設定

Claude と Supabase MCP の関係

Supabase MCP は、Supabase 公式コミュニティが管理する MCP サーバーで、Claude などの MCP クライアントから Postgres データベース・Edge Functions・Storage・ログにアクセスするためのブリッジとして動作する。Claude 側はクライアントとして MCP プロトコルで接続し、ユーザーが自然言語で出した指示(「users テーブルの行数を教えて」「failed_jobs を確認したい」など)を、サーバー側が用意したツールへの呼び出しに翻訳して実行する。

Anthropic 側に専用機能はなく、MCP サーバー側が用意するツール定義を Claude が読み取って利用する一般的な仕組みなので、Claude Desktop でも Claude Code でも、対応する MCP クライアント機能を持つ環境であれば共通の接続設定で動かせる。ホスト URL は https://mcp.supabase.com/mcp で、HTTPS 経由の HTTP transport で利用するのが推奨フローになっている。

出典: Supabase Docs — Model Context Protocol

Supabase MCP で何ができるか

Supabase MCP は機能群を 8 つのツールグループに整理しており、用途に応じて有効化する範囲を切り替えられる。代表的なものは以下のとおり。

• Database: テーブル一覧、SQL 実行、マイグレーション適用
• Debugging: Postgres ログ取得、セキュリティアドバイザー、パフォーマンスアドバイザーの確認
• Development: API URL の取得、anon / service key の取得、TypeScript 型生成
• Edge Functions: 関数の一覧・取得・デプロイ
• Branching: 開発ブランチの作成・切替(有料プラン必須)
• Storage: バケット設定の確認(デフォルト無効)
• Account: プロジェクト・組織の管理(プロジェクトスコープ時は利用不可)
• Knowledge Base: Supabase 公式ドキュメントの検索

Claude Code を使う場合、特に効果が大きいのは Database の SQL 実行と Development の TypeScript 型生成で、「テーブル変更 → 型再生成 → クライアントコード修正」という一連のスキーマ追従作業をプロンプト 1 回で済ませられる。Debugging グループはバグ調査用に「Postgres エラーログを直近 1 時間ぶん取って」と頼める点が実務的にありがたい。

出典: supabase-community/supabase-mcp(GitHub)

接続手順

Claude 側の MCP 設定ファイル(Claude Desktop なら claude_desktop_config.json、Claude Code なら .mcp.json または ~/.claude/mcp.json)に Supabase MCP のエントリを追加する。実際の手順は以下の順序で進める。

1. Supabase ダッシュボードにログインし、対象プロジェクトの Project Settings から Project Ref(abc123xyz のような ID)を控える。
2. 同じダッシュボードの「Access Tokens」画面でパーソナルアクセストークンを発行し、SUPABASE_ACCESS_TOKEN として安全な場所に保管する(.env や OS キーチェーンを推奨、リポジトリ直書きは厳禁)。
3. Claude の MCP 設定ファイルを開き、mcpServers 配下に下記のブロックを追加する。

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REF&read_only=true",
      "headers": {
        "Authorization": "Bearer YOUR_SUPABASE_ACCESS_TOKEN"
      }
    }
  }
}

4. Claude Desktop の場合はアプリを再起動、Claude Code の場合は新しいセッションを開き直す。
5. Claude のチャット欄で「Supabase の MCP に接続できている?」と聞き、ツール一覧に supabase.* が並ぶことを確認する。

URL クエリで project_ref と read_only を渡しているのがポイントで、ここを省くと「全プロジェクト書き込み可能」というかなり広い権限になってしまう。検証フェーズではこの 2 つを必ず明示するのが安全側の組み方になる。

read-only モードを推奨する理由

Supabase MCP には URL クエリ read_only=true を付けるとサーバー側で読み取り専用ユーザーとして全クエリを実行する仕組みが入っており、INSERT / UPDATE / DELETE / DROP などの書き込み系 SQL は Postgres 側で拒否される。Claude が「うっかり DELETE FROM users」を生成して実行してしまう事故を、クライアント側のレビューに頼らずデータベースエンジン層で止められるのが大きい。

特に、Claude Code でエージェント的に長時間タスクを走らせる場合、ツール呼び出しの承認フローを毎回手動で挟むのは現実的ではなく、read_only=true をデフォルトにしておく運用が安全度と作業速度のバランスがよい。書き込みが必要なときだけ、書き込み専用の MCP エントリ(別 URL / 別トークン)を一時的に追加し、作業後に削除する運用が事故を最小化する。

公式ドキュメントでも「本番プロジェクトへの直接接続は避け、開発用プロジェクトのみで使うべき」「機械学習システムとのデータ接続にはセキュリティリスクが伴う」と明記されており、MCP クライアントが任意のプロンプトを実行する性質上、SQL インジェクション類似のリスクをデータベース層で抑える設計が必要になる。

project_ref で対象プロジェクトを限定する

project_ref=<ID> を URL クエリで指定すると、その MCP コネクションは指定プロジェクト 1 つに完全に閉じる。Account グループのプロジェクト作成・削除や、別プロジェクトのデータベース操作は自動的に無効化されるため、誤って隣の検証環境を触ってしまう事故を防げる。

複数プロジェクトを切り替えたい場合は、mcpServers の中に supabase_dev / supabase_staging のように別名で複数エントリを並べておき、それぞれ別の project_ref を割り当てるのがおすすめのパターンになる。Claude にとっては別の MCP サーバーとして見えるので、「staging の users テーブルを見て」「dev の migrations を確認して」という指示も曖昧さなく届く。

features で機能を絞り込む

features=<group1>,<group2> クエリで、有効化するツールグループをホワイトリスト指定できる。たとえば features=database,docs のように書けば、Database と Knowledge Base のツールだけが Claude から見える状態になり、Edge Functions のデプロイや Account 操作を物理的に呼べないようにできる。

「Claude には DB の検査と公式ドキュメント検索だけ任せたい、デプロイは人間 + CI に閉じたい」というポリシーの場合、read_only=true と features=database,docs の組み合わせが最小権限の出発点として使いやすい。後から「TypeScript 型生成も任せたい」と判断したタイミングで features に development を足せばよく、必要なときだけ広げる運用に自然と寄せられる。

セキュリティと運用上の注意点

MCP サーバー経由でデータベースに自然言語が届く以上、プロンプトインジェクションを通じて意図しない操作が走るリスクを前提に運用する必要がある。Supabase 公式は以下のような対策を案内している。

• 本番プロジェクトに直接 MCP を繋がない: 必ず開発用 / ステージング用のプロジェクトを切る。
• アクセストークンの権限を最小化: 個人トークンを共有チャットや CI ログに出さない、定期的にローテーションする。
• ツール呼び出しを手動承認: 重要操作は Claude 側の confirmation を有効にし、SQL 内容を必ず目視確認する。
• read-only をデフォルトに: 書き込みは別エントリで一時的にのみ許可する。
• project_ref で対象を限定: 全プロジェクト権限のトークンを常時アタッチしない。

これらは公式ドキュメントが「セキュリティ推奨事項」として明示している項目で、開発スピードを優先するチームでも最低限ここまでは詰めておかないと、PR レビューで「なぜ本番 DB に直で繋がる構成?」という指摘を受けやすい。AI 連携のメリットを安全に取り切るために、最初の .mcp.json を書く段階でガードを入れ込んでおく価値は十分にある。

まとめ

Claude × Supabase MCP の現実的な始め方は、(1) パーソナルアクセストークンと Project Ref を控える、(2) claude_desktop_config.json または .mcp.json に read_only=true と project_ref 付きの URL を書く、(3) features で必要なツールグループだけホワイトリスト化する、という最小構成に集約できる。書き込みは別エントリ + 別トークンで臨時に開閉する運用にしておくと、Claude にスキーマ追従と調査タスクを任せつつ本番事故を構造的に避けられる。

出典:

• Supabase Docs — Model Context Protocol
• supabase-community/supabase-mcp(GitHub)