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 套件匯出 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，它不是此套件的相依項目。請一併安裝。

其他 MCP 伺服器

@supabase/mcp-server-postgrest

PostgREST MCP 伺服器允許您透過 REST API 將您自己的使用者連接到您的應用程式。請參閱其專案 README以了解更多詳情。

資源

• Model Context Protocol：深入了解 MCP 及其功能。
• 從開發到生產：了解如何安全地將變更推送到生產環境。

給開發者

請參閱 CONTRIBUTING 以了解如何為此專案貢獻。

授權

此專案採用 Apache 2.0 授權。請參閱 LICENSE 檔案以了解詳情。