Claude Code に Supabase MCP を追加する方法：設定ガイド

結論

Claude Code に Supabase MCP を追加するには、claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp" を実行し、通常のターミナルで claude を起動して /mcp と入力し、supabase を選んで Authenticate を選択し、ブラウザで Supabase にログインします。プロジェクトがある Organization を選べば、Claude がテーブル一覧の取得、SQL の実行、マイグレーションの適用、ログの確認を行えるようになります。

これは supabase-community/supabase-mcp による Supabase 公式のホスト型サーバーで、mcp.so では Supabase MCP として掲載しています。本格的に使う前に、以下の安全設定に 2 分だけ目を通してください。単一プロジェクトへの限定も読み取り専用モードも、URL パラメーターを付けるだけです。

必要なもの

• インストール済みでサインイン済みの Claude Code。
• プロジェクトが 1 つ以上ある Supabase アカウント。まずは開発用プロジェクトで始めるのが正解です。
• OAuth ログイン用のブラウザ。対話的に使う分には API キーは不要です。

ローカルにインストールするものはありません。サーバーはリモートの Streamable HTTP エンドポイントで、Claude Code は https://mcp.supabase.com/mcp に直接接続します。

ステップ 1：サーバーを追加する

Supabase MCP のドキュメントにあるコマンドです。

claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp"

Supabase は --scope project を使っており、リポジトリのルートにある .mcp.json にサーバーが書き込まれます。

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp"
    }
  }
}

各開発者が自分の Supabase アカウントでサインインするため、このファイルにシークレットは含まれず、安心してコミットできます。ほかのスコープも使えます。

スコープ、優先順位、承認の一般的な仕組みは Claude Code MCP ガイドをご覧ください。

ステップ 2：OAuth でログインする

1. 通常のターミナルで claude を起動する。Supabase のドキュメントでは、IDE 拡張ではなくターミナルで認証するよう明記されています。
2. /mcp と入力する。
3. supabase を選び、Authenticate を選択する。
4. ブラウザで Supabase にログインし、対象のプロジェクトがある Organization を選ぶ。
5. Claude Code に戻ると、/mcp で supabase が接続済みと表示されます。

トークンは Claude Code が保存・更新します。内部の流れが気になる方は MCP の認証と OAuth をご覧ください。

ステップ 3：単一プロジェクトに限定し、読み取り専用にする

パラメーターなしの URL では、選んだ Organization 内のすべてのプロジェクトに書き込み権限付きでアクセスできてしまいます。Supabase 自身のセキュリティガイドも範囲を絞ることを推奨しています。設定はすべて URL のクエリパラメーターで行います。

プロジェクトの ref は、ダッシュボードの URL supabase.com/dashboard/project/your-project-ref に含まれる ID です。プロジェクトを限定した読み取り専用の設定は次のとおりです。& はシェルにとって特別な意味を持つので、引用符は外さないでください。

claude mcp add --scope project --transport http supabase \
  "https://mcp.supabase.com/mcp?project_ref=your-project-ref&read_only=true"

すでにサーバーを追加している場合は、先に claude mcp remove supabase を実行するか（project スコープにあるなら --scope project を付ける）、.mcp.json の url を直接編集します。その後、再度認証が必要です。

機能グループ

Storage 以外のグループはデフォルトで有効です。features パラメーターに指定できる値は次のとおりです。

アプリ開発なら features=database,docs,debugging,development が手頃な出発点です。チャットから関数をデプロイしたりプロジェクトを作成したりはできなくなりますが、Claude が選ぶべきツール定義も減ります。なお、project_ref を設定するとアカウント系ツールは常に除外されます。

手で書くよりクリックで設定したい場合は、Supabase MCP のページに対話式の URL ビルダーがあります。

ステップ 4：確認する

claude mcp list

続いてセッション内で /mcp を開くと、supabase が接続済みでツール一覧が表示されるはずです。まずは無害な質問から試します。

Use the supabase MCP to list the tables in my project and their row-level security status.

project_ref で限定していれば、Claude がどのプロジェクトか尋ねてくることはありません。

プロンプト例

• 「テーブルを一覧にして、RLS が無効なものを教えて。」
• 「auth.users に紐づく profiles テーブルを追加するマイグレーションを書いて。ユーザーが自分の行だけを読み書きできる RLS ポリシーも付けて。適用前に見せて。」
• 「データベースの TypeScript 型を生成して、src/types/supabase.ts に保存して。」
• 「セキュリティとパフォーマンスのアドバイザーを確認して、一番重要な問題を直して。」
• 「直近 1 時間の API ログを見て、500 エラーの原因を説明して。」
• 「テーブルで realtime を設定する方法を Supabase のドキュメントで調べて、ここに実装して。」

型生成のプロンプトは、これがチャットアプリではなく Claude Code 向きである理由をよく示しています。Claude が MCP 経由で実際のスキーマを読み、その結果を直接リポジトリに書き込めるからです。

トークンを使う（CI やヘッドレス実行）

OAuth にはブラウザが必要なので、CI での claude -p のような非対話的な実行では完了できません。Supabase のドキュメントでは、代わりに個人アクセストークンを使う方法が紹介されています。

1. supabase.com/dashboard/account/tokens でトークンを作成する。接続先のプロジェクトに限定し、有効にしたツールに必要な権限だけを付与します。
2. CI 環境に SUPABASE_ACCESS_TOKEN と SUPABASE_PROJECT_REF を設定する。
3. それらを参照する設定をコミットする。Claude Code は .mcp.json の URL とヘッダー内の環境変数を展開します。

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

本物のトークンを絶対にファイルに書かないでください。このような無人の監視・診断ルーチンには、Supabase も読み取り専用モードを推奨しています。

ローカル環境とセルフホストの Supabase

Supabase CLI でローカルに Supabase を動かしている場合、MCP サーバーは http://localhost:54321/mcp にあります。

claude mcp add --transport http supabase-local http://localhost:54321/mcp

README によると、ローカルとセルフホストの環境ではツールが一部に限られ、OAuth 2.1 にも対応していません。セルフホストのインスタンスについては、Supabase の「Enabling MCP server」ガイドに従ってください。

セキュリティチェックリスト

Supabase のドキュメントはリスクについて非常に率直です。要点は次のとおりです。

• 本番環境には接続しない。 タスクが本番データを本当に必要とする場合を除き、開発用プロジェクトかブランチを使います。
• 見るだけなら読み取り専用モードを使う。
• project_ref で単一プロジェクトに限定する。
• Claude Code でツール呼び出しの手動承認をオンのままにする。 特に execute_sql と apply_migration は要注意です。
• プロンプトインジェクションに注意する。 データベースの行にはユーザーが書いたテキストが含まれることがあります。「これまでの指示を無視せよ」と書かれた行を Claude が読めば、その文章がモデルに届きます。承認する前に提案内容を確認しましょう。
• エンドユーザーにサーバーを渡さない。 これはあなたの権限で動く開発者向けツールです。

詳しくは MCP セキュリティのベストプラクティスをご覧ください。

トラブルシューティング

生のツール一覧とレスポンスを確認したい場合は、サーバーを MCP Inspector に接続してください。

次のステップ

Supabase MCP はデータベース側を担当します。GitHub MCP サーバーを追加すれば、Claude が書いたマイグレーションの PR を開けますし、Playwright MCP で機能をブラウザ上で確認できます。ほかのデータベースやバックエンドツールは、MCP サーバーディレクトリで探してください。