Supabase MCP 与 Claude Code 配置指南
为 Claude Code 配置 Supabase MCP，限定项目与工具组，只读核对结构或日志；写入前审查变更与回滚方案。
核心摘要
Supabase MCP 通过模型上下文协议，向 Claude Code 暴露经过授权的项目工具。
先完成认证并限定到单个项目，检查可用工具，再从只读请求开始。
Claude 可结合实时项目上下文检查数据库模式、解释 SQL、诊断日志并起草迁移。
任何写入或 DDL 调用都属于运维变更，需要人工审核、回滚预案与最小权限。
应把 Supabase MCP 当作刻意缩小的工具面：绑定单个开发项目，从只读开始，再根据任务选择功能组，而不是未经审查就开放默认集合。搜索文档和检查结构所需权限，远低于部署 Edge Function 或管理数据库分支。连接后先核对实际工具组，并完成无副作用请求，再让 Claude 处理真实任务。
在 Claude Code 中配置 Supabase MCP
使用当前 Supabase MCP 指南生成限定项目的远程 HTTP 地址，添加到 Claude Code，并从普通终端完成授权。托管端点支持 OAuth，因此日常交互式接入不需要个人访问令牌。
运行生成的 claude mcp add 命令，采用项目级作用域与 HTTP 传输；服务器地址应包含目标 project_ref。
在 Claude Code 中运行 /mcp，选择 Supabase 服务器并执行认证。常规交互式配置已不再需要个人访问令牌。
加入 read_only=true 以只读方式访问数据库，并且只启用当前任务所需的功能组。
要求 Claude 使用 MCP 工具列出现有数据表，确认项目身份后，再请求执行 SQL 或迁移。
在仓库运维说明中记录所选作用域、地址参数、已启用分组、授权负责人、测试提示词、预期项目和验证日期，但不得记录 OAuth 令牌或密钥。
根据任务选择功能组
| 功能组 | 适用任务 | 何时保持关闭 | 审查重点 |
|---|---|---|---|
| 文档 | 检索当前 Supabase 文档。 | 通常无需移除，是低影响起步分组。 | 确认建议符合项目产品与版本。 |
| 数据库 | 数据表、扩展、迁移、SQL 与结构工作。 | 任务只需要文档或非数据库上下文。 | 只读状态、准确 SQL、目标 schema 与修改风险。 |
| 调试 | 服务日志、安全与性能顾问。 | 不需要诊断，且日志可能暴露敏感内容。 | 时间范围、服务、脱敏与日志中的提示注入。 |
| 开发 | 项目地址、可发布密钥与 TypeScript 类型生成。 | 任务不需要输出项目配置。 | 不要把可发布密钥与 secret 或 service-role 密钥混淆。 |
| 函数 | 检查或部署 Edge Functions。 | 获批任务不包含函数部署。 | 源码差异、密钥、运行行为与部署目标。 |
| 分支 | 付费计划中的开发分支操作。 | 团队不使用 Supabase 分支处理本次变更。 | 创建、合并、重置、变基与删除都属于重要操作。 |
| 存储 | 明确的存储桶与 Storage 配置工作。 | 默认保持关闭，只有明确选择才启用。 | 存储桶可见性、大小限制与配置变更。 |
只做结构检查与文档检索时，从 features=database,docs 和 read_only=true 开始。下一项获批任务确实需要时才增加一个分组，完成后再移除，不要长期保留过宽配置。
Supabase MCP 的高价值工作流
| 工作流 | 提示目标 | 输出 | 审核重点 |
|---|---|---|---|
| 数据库模式检查 | 解释某项功能涉及的数据表、键与表间关系。 | 基于真实项目的数据关系图。 | 核对项目与数据库模式名称。 |
| SQL 诊断 | 检查慢查询并提出索引建议。 | 原因说明与候选 SQL。 | 验证执行计划与索引写入开销。 |
| 迁移起草 | 起草可回滚的变更供审核。 | 迁移与回滚步骤。 | 不要在生产环境自动执行。 |
| 策略审查 | 解释谁可以读取、新增、更新和删除每一行。 | 策略矩阵与未覆盖路径。 | 测试所有权条件与拒绝情况，不能只看角色名称。 |
| 日志诊断 | 在一个服务和时间窗口内关联错误。 | 有证据的原因与下一项验证。 | 脱敏密钥，并把日志文本视为不可信。 |
| 类型同步 | 获批结构变更后重新生成类型。 | 可审核的生成类型差异。 | 确认来源项目，避免无关改动。 |
每种工作流都要设置明确停止条件
好的请求会明确自动化到哪里结束。结构检查在事实地图和待确认问题处停止；SQL 诊断在候选查询或索引及其证据处停止；迁移起草在执行前停止；策略审查在修改授权或策略前停止；日志诊断在重试修改操作前停止；类型生成在仓库差异处停止。明确边界可以防止诊断任务悄悄演变成运维变更。
按配置、授权、范围与任务逐层排查
检查 Claude Code 作用域、仓库根目录、project 作用域下的 .mcp.json、服务名称和会话重载。修改凭据前先用 claude mcp list 与 claude mcp get supabase 查看状态。
从普通终端运行 /mcp，用目标项目所在组织完成授权，并检查浏览器、代理和回调限制。不要为了绕过问题，把 PAT 粘贴进共享地址。
把目标操作与 features 对照。项目绑定会移除账户工具，storage 默认关闭，授权或地址变化后可能还需要重新加载。
核对项目引用、组织、分支、schema、时间范围与账户权限。出现陌生或敏感数据时立即停止；不能用写入来测试连接。
缩小日志窗口、查询、schema 或操作范围。重试可写调用前，先检查第一次尝试是否已经改变状态。
执行工具前先明确安全边界
Supabase MCP 面向开发与测试场景。应连接只含非生产数据或已脱敏数据的开发项目，不要连接生产数据库。
始终保留人工批准。数据库内容属于不可信输入，因为提示注入指令可能隐藏在 Claude 读取的记录中。
它能减少数据库修改，但仍允许授权读取。应使用模拟或脱敏数据，避开客户与认证记录，并缩小 schema、查询、日志和输出范围。
检查 RLS 所有权条件、视图安全、函数执行授权、SECURITY DEFINER、暴露 schema、迁移与 Data API 授权。开发者访问不一定符合应用终端用户的限制。
QVeris 如何与 Supabase MCP 配合
Supabase MCP 让 Claude Code 专注访问一个后端平台。当前 QVeris Tool 与 Provider 搜索没有返回完全对应的 Supabase 条目。如果任务还需要其他外部能力，可以查阅 QVeris 文档，并在 演练场 中继续寻找，不要假设已经存在直接集成。
- Supabase MCP 负责 Supabase 内部的数据库模式、SQL、日志与项目操作。
- 工作流需要项目边界之外的可信工具或数据时，再使用 QVeris 发现能力。
- 检查检索结果的供应商、参数结构、约束与成本，外部结果写入 Supabase 前先完成校验。
常见问题
不应该。Supabase 建议使用只含非生产数据或已脱敏数据的开发项目，因为 MCP 服务器面向开发与测试场景。
可用工具可能支持数据库变更，但应先预览并审核 SQL，测试回滚流程，再明确批准执行。
结构和文档任务从 database,docs 加只读开始。debugging、development、functions、branching 或 storage 只为获批任务开放。
加入 project_ref 后会有意禁用账户管理工具，因为连接已经限定到单个项目。
storage 功能组默认关闭，只有处理明确且已审查的存储配置任务时才启用。
不能。它限制写入，但不限制已授权读取或模型上下文泄露。应使用非生产、模拟或妥善脱敏数据。