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 套件匯出 createToolSchemas()，用於為 Vercel AI SDK 的 MCP 用戶端填入輸入和輸出架構。這使得 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 套件匯出 createSupabaseMcpHandler()，用於從您自己的端點透過 HTTP 提供工具服務。它接受與 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 檔案以了解詳情。