Supabase MCP Server

什么是 Supabase MCP Server？

Supabase MCP 是 Supabase 官方的 Model Context Protocol 服务器，可将 Cursor、Claude、Windsurf 等 AI 助手连接到你的 Supabase 项目，让它们管理数据表、运行 SQL 和迁移、获取配置、读取日志并部署 Edge Functions。

它是一个托管服务器，地址为 https://mcp.supabase.com/mcp，通过 OAuth 登录，因此大多数情况下无需安装，也不需要访问令牌。代码位于 supabase-community/supabase-mcp 仓库，采用 Apache-2.0 许可证。本地 Supabase CLI 和自托管 Supabase 同样提供 MCP 端点，但工具较少且不支持 OAuth。

如何使用 Supabase MCP Server？

开始之前： 请阅读 Supabase 的安全指南。将 LLM 连接到数据库存在实际风险，因此建议使用开发项目、保持对工具调用的手动审批，并考虑启用只读模式。

服务器 URL： https://mcp.supabase.com/mcp。配置过程中，客户端会打开浏览器让你登录 Supabase；请选择包含目标项目的组织。你也可以在 Supabase 控制台 Connect 对话框的 MCP 标签中生成针对特定项目的 URL。

URL 选项（查询参数）：

• project_ref=<id>：将服务器限定在一个项目内，并禁用账户级工具
• read_only=true：以只读 Postgres 用户身份执行所有查询
• features=database,docs：只启用列出的工具组

Claude Code

claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp"

然后在普通终端（而非 IDE 扩展）中运行 claude /mcp，选择 supabase，再选择 Authenticate。

Cursor

在 .cursor/mcp.json（或对所有项目生效的 ~/.cursor/mcp.json）中添加：

{
  "mcpServers": {
    "supabase": {
      "url": "https://mcp.supabase.com/mcp"
    }
  }
}

VS Code

在 .vscode/mcp.json 中添加：

{
  "servers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp"
    }
  }
}

Codex

codex mcp add supabase --url "https://mcp.supabase.com/mcp"
codex mcp login supabase

在 Codex 中使用 /mcp 进行验证。

其他客户端

在 Claude.ai 中，可以从连接器目录添加 Supabase。对于其他客户端，将通用配置转换为该客户端所需的格式：

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp"
    }
  }
}

在 CI 或无法使用浏览器流程的客户端中，创建一个限定权限的个人访问令牌，并通过 Authorization: Bearer 请求头发送。在本地运行 Supabase CLI 时，服务器地址为 http://localhost:54321/mcp。

Supabase MCP Server 的主要功能

• 官方托管服务器，支持 OAuth 2.1 登录：大多数客户端无需本地安装或令牌
• 覆盖项目、数据库、Edge Functions、日志、顾问检查、分支、存储和文档的工具
• read_only=true 模式，以只读 Postgres 用户执行 SQL
• 通过 project_ref 限定项目，让智能体只在一个项目内操作
• 通过功能组只暴露任务所需的工具
• 创建项目或分支前进行费用确认
• 可配合本地 Supabase CLI 和自托管 Supabase 使用（工具有限）
• @supabase/mcp-server-supabase 包可为 Vercel AI SDK 提供带类型的工具 schema

Supabase MCP Server 工具

本页面列出了 29 个工具，按功能组划分。除 Storage 外，所有功能组默认启用。

• 账户： list_organizations、list_projects、create_project、pause_project 和 restore_project。get_cost 和 confirm_cost 要求智能体在创建项目或分支前说明并确认费用。
• 数据库： list_tables、list_extensions、list_migrations、用于 DDL 的 apply_migration，以及用于查询的 execute_sql。
• 调试： query_logs 和 get_advisors 提供日志以及安全或性能方面的建议。
• 开发： get_project_url、get_publishable_keys 和 generate_typescript_types。
• Edge Functions： list_edge_functions、get_edge_function 和 deploy_edge_function。
• 分支（实验性，需付费套餐）： create_branch、merge_branch、reset_branch、rebase_branch 和 delete_branch。
• 文档： search_docs 用于检索 Supabase 文档。

Supabase MCP Server 的使用场景

• 表结构工作：“Create a profiles table linked to auth.users with row level security, as a migration.”
• 数据问答：“How many users signed up last week? Use read-only SQL.”
• 调试：“Check the API logs for errors in the last hour and run the security advisor.”
• 前端类型：“Generate TypeScript types for my database and update types.ts.”
• Edge Functions：“Deploy a function that sends a welcome email on signup.”
• 安全试验：“Create a development branch, apply this migration there, and show me the diff.”

Supabase MCP Server 与替代方案对比

Supabase MCP 服务器了解项目、Edge Functions、顾问检查和分支等 Supabase 特有功能。如果你只需要通过 SQL 访问 Postgres 数据库（包括通过连接字符串访问 Supabase 数据库），Postgres MCP 这类通用服务器也可以，但无法管理平台本身。GitHub 上也有一些较早的、名为“supabase-mcp”的社区项目；官方托管服务器才是持续维护的选择。

Supabase MCP Server 常见问题排查

• 项目错误或缺失： OAuth 时选择了不包含该项目的组织。重新认证并选择正确的组织，或在 URL 中用 project_ref 限定项目。
• Claude Code 无法完成认证： 在普通终端而非 IDE 扩展中运行 claude /mcp，然后选择 supabase 并点击 Authenticate。
• 缺少写入类工具： URL 中带有 read_only=true，它会禁用这些工具。只在非生产项目中移除该参数。
• 工具比预期少： 本地 CLI 和自托管环境只提供部分工具且不支持 OAuth，Storage 也默认关闭。可通过 features= 添加功能组。
• CI 中没有浏览器： 用限定权限的个人访问令牌，通过 Authorization: Bearer 请求头代替 OAuth。