Supabase 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 から取得されますが、これはこのパッケージの依存関係ではありません。一緒にインストールしてください。

その他の MCP サーバー

@supabase/mcp-server-postgrest

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

リソース

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

開発者向け

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

ライセンス

このプロジェクトは Apache 2.0 ライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。