Supabase MCP

npx add-mcp 'https://mcp.supabase.com/mcp'

Supabase MCP サーバー

SupabaseプロジェクトをCursor、Claude、Windsurf、その他のAIアシスタントに接続します。

Model Context Protocol（MCP）は、大規模言語モデル（LLM）がSupabaseのような外部サービスと通信する方法を標準化します。AIアシスタントをSupabaseプロジェクトに直接接続し、テーブルの管理、設定の取得、データのクエリなどのタスクを実行できるようにします。全ツール一覧をご覧ください。

セットアップ

1. セキュリティのベストプラクティスに従う

MCPサーバーを設定する前に、セキュリティのベストプラクティスをお読みいただき、LLMをSupabaseプロジェクトに接続するリスクとその軽減方法を理解することをお勧めします。

2. MCPクライアントを設定する

クライアントでSupabase MCPサーバーを設定するには、セットアップドキュメントをご覧ください。また、SupabaseダッシュボードのMCP接続タブにアクセスして、プロジェクト用のカスタムMCP URLを生成することもできます。

セットアップ中、MCPクライアントは自動的にSupabaseへのログインを求めます。作業したいプロジェクトが含まれる組織を必ず選択してください。

ほとんどのMCPクライアントでは、以下の情報が必要です：

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

お使いのMCPクライアントがドキュメントに記載されていない場合は、クライアントのMCPドキュメントを確認し、上記のMCP情報をクライアントの期待する形式（json、yamlなど）にコピーしてください。

CLI

Supabase CLIを使用してSupabaseをローカルで実行している場合、http://localhost:54321/mcpでMCPサーバーにアクセスできます。現在、CLI環境のMCPサーバーは限られたツールセットを提供し、OAuth 2.1には対応していません。

セルフホスト

セルフホスト型Supabaseの場合は、MCPサーバーの有効化ページを確認してください。現在、セルフホスト環境のMCPサーバーは限られたツールセットを提供し、OAuth 2.1には対応していません。

設定オプションとツール

利用可能なツールと設定オプションの完全なリストについては、Supabase MCPサーバーのドキュメントをご覧ください。

ドキュメントには、設定オプションを自動的に入力するインタラクティブなURLビルダーも用意されています。

AI SDKのMCPクライアントでの使用

@supabase/mcp-server-supabaseパッケージは、Vercel AI SDKのMCPクライアント用の入力および出力スキーマを設定するcreateToolSchemas()をエクスポートします。これにより、Supabase MCPツールを、クライアント側の検証と入力・出力の推論されたTypeScript型を持つ静的ツールとして扱うことができます。

import { createToolSchemas } from '@supabase/mcp-server-supabase';
import { createMCPClient } from '@ai-sdk/mcp';
import { streamText } from 'ai';

const mcpClient = await createMCPClient({
  transport: {
    type: 'http',
    url: 'https://mcp.supabase.com/mcp',
  },
});

const tools = await mcpClient.tools({
  schemas: createToolSchemas(),
});

const result = streamText({ model, tools, prompt: '...' });

for (const step of await result.steps) {
  for (const toolResult of step.staticToolResults) {
    if (toolResult.toolName === 'get_project_url') {
      toolResult.input;  // { project_id: string }
      toolResult.output; // { url: string }
    }
  }
}

createToolSchemas()は、MCPサーバーのURLパラメータと同様のフィルタリングオプションを受け付けます：

• features：特定の機能グループに制限します（例：['database', 'docs']）。デフォルトはすべてのデフォルト機能グループです。
• projectScoped：trueの場合、ツール入力スキーマからproject_idを省略し、アカウントレベルのツールを除外します — project_refで設定されたサーバーに接続するときに使用します。デフォルトはfalseです。
• readOnly：trueの場合、変更を加えるツールを除外します — read_only=trueで設定されたサーバーに接続するときに使用します。デフォルトはfalseです。

const mcpClient = await createMCPClient({
  transport: {
    type: 'http',
    url: 'https://mcp.supabase.com/mcp?project_ref=<project-ref>&read_only=true&features=database,docs',
  },
});

const tools = await mcpClient.tools({
  schemas: createToolSchemas({
    features: ['database', 'docs'],
    projectScoped: true,
    readOnly: true,
  }),
});

[!NOTE] このサーバーはMCPツールの結果にstructuredContentを送信しません。AI SDKはcontentテキストからJSONを解析することにフォールバックします。

詳細については、AI SDKドキュメントのスキーマ定義と型付きツール出力を参照してください。

MCPエンドポイントのセルフホスティング

@supabase/mcp-server-supabaseパッケージは、独自のエンドポイントからHTTP経由でツールを提供するcreateSupabaseMcpHandler()をエクスポートします。これはcreateSupabaseMcpServer()と同じSupabaseMcpServerOptionsを受け付けますが、最も重要なのはplatformです。

このハンドラーは現在のプロトコルリビジョンのみをサポートします。legacy: 'reject'で作成されるため、2025年時代のプロトコルのみをサポートするクライアントは、サービス提供の代わりにHTTP 400を受け取ります。

platformがリクエストごとの認証情報を保持する場合、リクエストごとにハンドラーを作成し、レスポンスが完了したら閉じます。ハンドラーは指定したplatformをクロージャで保持するため、共有されたものはそのプラットフォームで全てのリクエストにサービス提供します。

platformが共有されることを意図している場合（サービスアカウントトークンなど）、長時間稼働するハンドラーで問題ありません。レスポンスごとではなく、シャットダウン時に一度作成してclose()します。close()はサブスクリプションルーターを破棄し、以降のリクエストを拒否するためです。

import { createServer } from 'node:http';
import { toNodeHandler } from '@modelcontextprotocol/node';
import { createSupabaseMcpHandler } from '@supabase/mcp-server-supabase';
import { createSupabaseApiPlatform } from '@supabase/mcp-server-supabase/platform/api';

const server = createServer((req, res) => {
  const accessToken = getAccessTokenFromRequest(req); // your own auth

  const handler = createSupabaseMcpHandler({
    platform: createSupabaseApiPlatform({ accessToken }),
  });

  // `close()` aborts in-flight exchanges, so close on `res` finishing rather
  // than when the handler resolves, which would cut streaming responses short.
  res.on('close', () => {
    handler.close().catch((error) => console.error(error));
  });

  toNodeHandler(handler)(req, res).catch((error) => console.error(error));
});

toNodeHandlerは@modelcontextprotocol/nodeから取得されます。コードは直接インポートするため、一緒にインストールしてください。

可観測性

observerをcreateSupabaseMcpServerに渡すと、リクエストライフサイクルの結果とSupabaseの組み込みファクトを収集できます。ここで、platformは既存のプラットフォームアダプターです：

import { createSupabaseMcpServer } from '@supabase/mcp-server-supabase';

const server = createSupabaseMcpServer({
  platform,
  observer: (context) => ({
    record(fact) {
      console.info(fact);
    },
    end(result) {
      console.info({ ...context, ...result });
    },
  }),
});

サーバーはリクエストまたはレスポンスのペイロードをオブザーバーに自動的に転送しません。Supabaseの組み込みファクトは、境界のあるフィールドと値の閉じたセットを使用します。カスタムファクトは自動的なプライバシー検証を受けません。observerを省略すると、すべての観測作業がスキップされます。オブザーバー、分類器、シンクの障害はリクエストの動作を変更しませんが、同期オブザーバーと分類器の作業はリクエストをブロックする可能性があります。

その他のMCPサーバー

@supabase/mcp-server-postgrest

PostgREST MCPサーバーを使用すると、REST APIを介して自分のユーザーをアプリに接続できます。詳細はプロジェクトREADMEをご覧ください。

リソース

• Model Context Protocol：MCPとその機能について詳しく学ぶ。
• 開発から本番環境へ：変更を本番環境に安全に反映する方法を学ぶ。

開発者向け

このプロジェクトへの貢献方法の詳細については、CONTRIBUTINGをご覧ください。

ライセンス

このプロジェクトはApache 2.0ライセンスの下で提供されています。詳細はLICENSEファイルをご覧ください。