如何将 Supabase MCP 接入 Claude Code
在 Claude Code 注册 Supabase MCP，完成浏览器授权并验证限定范围的只读请求，再批准开发环境变更。
核心摘要
使用 Claude CLI 添加 Supabase 托管的 HTTP 端点，再在普通终端的 /mcp 菜单中完成认证。
通过 project_ref 限定单个项目，启用 read_only=true，并且只开放任务需要的功能组。
修改任何内容前，核对地址、连接状态、所选组织、工具清单，并用结果已知的只读元数据查询完成验证。
只有在隔离开发分支中，并且 SQL、迁移、回滚与测试计划都经过审查后，才考虑移除只读。
本指南采用 Supabase 官方托管 MCP 路径：准备非生产项目、选择 Claude Code 作用域、生成受限地址、注册远程 HTTP 服务、完成 OAuth、在需要时批准项目配置，最后用无副作用请求证明连接正确。验收标准不是“列表里出现了服务器”，而是能够证明 Claude 只通过预期工具访问了正确项目。
将 Supabase MCP 添加到 Claude Code
应从当前 Supabase MCP 指南开始，因为端点参数和功能组可能更新。在配置面板中选择托管平台、目标开发项目、Claude Code、只读模式，以及当前真正需要的功能，再复制生成命令，不要凭记忆拼接地址。
运行命令前先决定 Claude Code 作用域
| 作用域 | 适用情况 | 配置表现 | 审查重点 |
|---|---|---|---|
| 项目级 | 代码仓库需要向团队共享同一服务定义。 | 定义写入仓库级 .mcp.json。 | 提交前审查并批准文件，绝不能包含令牌。 |
| 本地级 | 只有当前用户与当前仓库需要该连接。 | 定义不会进入团队共享的项目文件。 | 适合个人试用，但队友无法自动复现。 |
| 用户级 | 同一个人服务需要跨多个代码仓库使用。 | 让该连接对当前用户更广泛地可用。 | 不同仓库对应不同 Supabase 项目时不要使用。 |
更新 Claude Code，打开代码仓库根目录，并从 Supabase 复制开发项目引用。确认项目中没有生产数据或未脱敏客户数据，再决定团队需要 project 作用域，还是个人评估更适合 local。
选择目标项目、开启只读，并先只勾选 database,docs。生成结果应使用 https://mcp.supabase.com/mcp，并包含 project_ref、read_only=true 和较短的 features 参数。绑定项目后也会移除账户管理工具。
运行 claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REF&read_only=true&features=database,docs"。替换项目占位符；只有前一步决定使用个人配置时，才调整作用域。
从普通终端启动 Claude Code，输入 /mcp，选择 supabase 和 Authenticate，再登录目标项目所在组织。正常交互式使用依靠 OAuth，不需要个人访问令牌。
project 作用域的定义来自代码仓库，可能需要先信任工作区并明确批准。批准前再次审查地址；如果授权成功但工具尚未出现，请重新加载会话。
不要把凭据粘贴进命令。项目引用用于识别项目，但它不是授权密钥；OAuth 凭据会单独处理。个人访问令牌仅适用于无法交互登录的场景，应保存在密钥系统中，不能写入仓库里的地址。
变更数据前先验证服务器
先输入：“列出该项目的数据表及其 schema，不要执行写入。”把结果与 Supabase 控制台核对无误后，再考虑开放变更操作。
| 检查项 | 安全请求 | 预期依据 | 停止条件 |
|---|---|---|---|
| 项目身份 | 运行 claude mcp get supabase。 | URL 包含正确的 project_ref。 | 项目标识缺失或错误。 |
| 数据库 | 只列出 schema 和数据表。 | 名称与控制台一致。 | 出现敏感或未知 schema。 |
| 权限 | 说明可用的 MCP 工具。 | 仅显示已选择的功能组。 | 启用了意外的变更工具。 |
用五项验收标准确认接入成功
- 定义：
claude mcp get supabase显示 HTTP 传输、正确作用域、准确项目引用、只读参数与所选功能。 - 可访问性：服务进入授权状态，而不是启动失败或连接超时。
- 授权：
/mcp显示 Supabase 已通过正确组织连接。 - 工具：database 和 docs 工具可见，未选择的分组与账户工具不应出现。
- 结果：查询已知表清单，与控制台一致，且没有执行修改数据的 SQL。
按同一顺序定位失败环节
从目标仓库重新运行命令，核对作用域与服务名称；使用 project 作用域时检查 .mcp.json，然后重新加载 Claude Code。在其他目录创建的配置不会自动应用到当前仓库。
核对地址域名与传输方式，检查代理或防火墙，再从普通终端重新完成授权。不要为了绕过浏览器问题，就改为直接粘贴令牌。
检查 features 参数。Storage 默认关闭，项目绑定会排除账户管理，而且授权或配置变化后客户端可能需要重新加载。
重新核对项目引用、所选组织、数据库分支、schema 与账户权限。发现陌生 schema 或敏感数据时应立即停止，不要通过写入测试记录来“确认”连接。
落实最小权限并防范提示词注入
URL 如果没有 project_ref，可能暴露已认证账号能够访问的全部项目；限定项目后，账号管理工具会被禁用。使用 features=database,docs 或更短的列表，不要默认开放全部功能组。
read_only=true 会让数据库查询以只读 Postgres 用户身份执行。Supabase 同时建议仅在开发和测试场景使用该 MCP 服务器，不要连接生产数据。
数据库内容可能包含提示词注入指令。批准前应检查每一次工具调用和 SQL 语句；Supabase 对查询结果的保护性封装可以降低风险，但无法提供绝对防护。
只读角色能够阻止数据库修改，却不能阻止敏感数据进入模型上下文或输出。应使用开发数据，缩小 schema 和功能组范围，并让测试项目远离客户记录与认证数据。
确实需要写入时，先要求生成迁移计划、SQL、受影响对象、回滚方案和测试。获批后只在隔离分支执行，运行数据库顾问、检查差异，再按团队常规流程合并。
用 QVeris 扩展 Supabase 项目之外的能力
Supabase MCP 用于把 Claude Code 接入单一后端平台。实时检索 QVeris Tool 与 Provider 目录后，没有发现完全对应的 Supabase 条目。如果任务还需要其他外部能力，可以查阅 QVeris 文档，并在 演练场 中继续寻找；不要把它理解成现成的 Supabase 直接集成。
- 数据库检查与修改始终留在官方 Supabase MCP 权限边界内。
- 遇到独立外部任务时，通过 QVeris 检索当前能力，并在调用前检查供应商、参数结构、约束与成本。
- 外部结果写入 Supabase 前必须校验，并在跨系统边界保留人工确认。
常见问题
常规交互式使用不需要。托管服务器会打开 OAuth 浏览器流程；个人访问令牌主要用于无法交互登录的 CI 环境。
仓库需要共享已审查定义时用 project；单个用户与单个仓库用 local；只有同一个人连接确实需要跨项目时才用 user。
项目 MCP 定义来自仓库文件。请在该仓库打开 Claude Code，审查地址，在合适时信任工作区并批准服务。
Storage 默认关闭，所选功能组决定工具可见性，而 project_ref 会有意禁用账户管理工具。
默认仍不安全，因为可读数据可能泄露或包含提示注入。Supabase 建议改用开发与测试数据。
先用 claude mcp get supabase 检查，再通过当前 Claude MCP 命令移除，添加修正后的定义后重新完成全部验证步骤。