Supabase MCP

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

Supabase MCP 服务器

将你的 Supabase 项目连接到 Cursor、Claude、Windsurf 及其他 AI 助手。

模型上下文协议（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。

资源

• 模型上下文协议：了解有关 MCP 及其功能的更多信息。
• 从开发到生产：了解如何安全地将更改推广到生产环境。

面向开发者

有关如何为此项目做贡献的详细信息，请参阅 CONTRIBUTING。

许可证

本项目根据 Apache 2.0 许可。详情请参阅 LICENSE 文件。