Supabase MCP Server

Supabase MCP サーバー

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

Model Context Protocol（MCP）は、Large Language Models（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,
  }),
});

メモ

このサーバーは、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 を使用します。

サービスアカウントトークンなど、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 から提供されます。コードから直接インポートするため、併せてインストールしてください。

可観測性

リクエストのライフサイクル結果と Supabase に組み込まれた事実を収集するには、createSupabaseMcpServer に observer を渡します。ここで、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 ファイルを参照してください。