Supabase MCP Server

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 等）中。

命令行

如果你使用 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,
  }),
});

说明

此服务不会在 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。

如果 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。你的代码会直接导入它，因此需要将其一并安装。

可观测性

向 createSupabaseMcpServer 传入 observer，即可收集请求生命周期结果和 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 文件。