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 文件。