如何把 Supabase MCP 添加到 Claude Code：配置教程

简短回答

要把 Supabase MCP 添加到 Claude Code，运行 claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp"，在普通终端中启动 claude，输入 /mcp，选择 supabase，点 Authenticate，然后在浏览器中登录 Supabase。选择包含你项目的组织后，Claude 就能列出数据表、执行 SQL、应用迁移和查看日志。

这是 Supabase 官方托管的服务器，来自 supabase-community/supabase-mcp，在 mcp.so 上收录为 Supabase MCP。在正式依赖它之前，花两分钟看看下面的安全选项：限定到单个项目和开启只读模式都只是 URL 参数而已。

你需要准备

• 已安装并登录的 Claude Code。
• 一个至少有一个项目的 Supabase 账号。从开发项目开始是正确的做法。
• 一个用于 OAuth 登录的浏览器。交互式使用不需要 API key。

本地不需要安装任何东西。这个服务器是远程 Streamable HTTP 端点，Claude Code 直接连接 https://mcp.supabase.com/mcp。

第 1 步：添加服务器

Supabase MCP 文档中的命令：

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

Supabase 使用 --scope project，它会把服务器写入仓库根目录的 .mcp.json：

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

这个文件不包含任何密钥，因为每个开发者都用自己的 Supabase 账号登录，所以可以放心提交。其他作用域也可以：

作用域、优先级和审批的通用规则，见 Claude Code MCP 指南。

第 2 步：用 OAuth 登录

1. 在普通终端中启动 claude。Supabase 文档特别说明要在终端中认证，而不是在 IDE 扩展里。
2. 输入 /mcp。
3. 选择 supabase，然后选 Authenticate。
4. 在浏览器中登录 Supabase，并选择包含目标项目的组织。
5. 回到 Claude Code，/mcp 会显示 supabase 已连接。

Claude Code 会保存并刷新令牌。想了解底层流程，可以看 MCP 认证与 OAuth。

第 3 步：限定到单个项目并设为只读

使用不带参数的 URL 时，Claude 可以访问你所选组织中的所有项目，并且拥有写权限。Supabase 自己的安全建议也推荐收窄范围。这些都通过 URL 查询参数完成：

项目 ref 就是控制台 URL 中的 ID，即 supabase.com/dashboard/project/your-project-ref。限定项目且只读的配置如下。注意保留引号，因为 & 对 shell 有特殊含义：

claude mcp add --scope project --transport http supabase \
  "https://mcp.supabase.com/mcp?project_ref=your-project-ref&read_only=true"

如果已经添加过服务器，先运行 claude mcp remove supabase（如果它在 project 作用域，加上 --scope project），或者直接编辑 .mcp.json 中的 url。之后需要重新认证。

功能组

除 Storage 外，所有功能组默认启用。features 参数接受以下值：

做应用开发时，features=database,docs,debugging,development 是一个合理的起点。这样就不能在对话中部署函数或创建项目，Claude 需要挑选的工具定义也更少。注意：只要设置了 project_ref，账号类工具就会被跳过。

如果你更喜欢点选而不是手写，Supabase MCP 页面提供了交互式 URL 生成器。

第 4 步：验证

claude mcp list

然后在会话中，/mcp 应显示 supabase 已连接并列出工具。先问一个无害的问题：

Use the supabase MCP to list the tables in my project and their row-level security status.

如果用 project_ref 做了限定，Claude 不需要再问你指的是哪个项目。

示例提示词

• 「列出我的数据表，告诉我哪些没有开启 RLS。」
• 「写一个迁移，新增一张关联 auth.users 的 profiles 表，并配置 RLS 策略，让用户只能读取和更新自己的那一行。应用之前先给我看。」
• 「为我的数据库生成 TypeScript 类型，保存到 src/types/supabase.ts。」
• 「检查安全和性能建议（advisors），修复最重要的一个问题。」
• 「看看最近一小时的 API 日志，解释一下那些 500 错误。」
• 「在 Supabase 文档中搜索如何为数据表开启 realtime，然后在这里实现。」

生成类型的提示词很好地说明了为什么这件事适合放在 Claude Code 而不是聊天应用里：Claude 通过 MCP 读取实时的数据库结构，并把结果直接写进你的仓库。

改用令牌（CI 和无界面运行）

OAuth 需要浏览器，所以像 CI 中的 claude -p 这样的非交互式运行无法完成它。Supabase 文档介绍了改用个人访问令牌的方法：

1. 在 supabase.com/dashboard/account/tokens 创建令牌。把它限定到服务器要连接的项目，只授予已启用工具所需的权限。
2. 在 CI 环境中设置 SUPABASE_ACCESS_TOKEN 和 SUPABASE_PROJECT_REF。
3. 提交一份引用这两个变量的配置。Claude Code 会展开 .mcp.json 中 URL 和请求头里的环境变量：

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp?project_ref=${SUPABASE_PROJECT_REF}&read_only=true",
      "headers": {
        "Authorization": "Bearer ${SUPABASE_ACCESS_TOKEN}"
      }
    }
  }
}

绝对不要在文件里写真实令牌。对于这类无人值守的监控和诊断任务，Supabase 推荐使用只读模式。

本地和自托管 Supabase

如果你用 Supabase CLI 在本地运行 Supabase，MCP 服务器地址是 http://localhost:54321/mcp：

claude mcp add --transport http supabase-local http://localhost:54321/mcp

根据 README，本地和自托管环境中的服务器只提供部分工具，也不支持 OAuth 2.1。自托管实例请参考 Supabase 的「Enabling MCP server」指南。

安全清单

Supabase 文档对风险说得非常直白。简要版本如下：

• 不要连接生产环境，除非任务确实需要生产数据。使用开发项目或分支。
• 只需要查看时就用只读模式。
• 用 project_ref 限定到单个项目。
• 在 Claude Code 中保持手动审批工具调用，尤其是 execute_sql 和 apply_migration。
• 警惕提示词注入。 数据库中的行可能包含用户写的文本。如果 Claude 读到一行写着「忽略之前的指令」，这段文字就会进入模型。批准之前先检查它提出的操作。
• 不要把服务器提供给终端用户。 它是以你的权限执行操作的开发者工具。

更多内容见我们的 MCP 安全最佳实践。

故障排查

想查看原始工具列表和返回内容，可以把服务器连接到 MCP Inspector。

下一步

Supabase MCP 负责数据库这一侧。再加上 GitHub MCP 服务器，让 Claude 为它写好的迁移创建 PR；加上 Playwright MCP 在浏览器中检查功能。更多数据库和后端工具，可以浏览 MCP 服务器目录。