Supabase MCP with Claude Code
Setup, Workflows & Safety在 Claude Code 中配置 Supabase MCP
工作流与安全实践
Give Claude Code controlled access to your Supabase database schema, SQL tools, logs, and project context through MCP.
通过 MCP 向 Claude Code 提供受控的 Supabase 数据库模式、SQL 工具、日志与项目上下文访问。
TL;DR核心摘要
Supabase MCP exposes approved project tools to Claude Code through the Model Context Protocol.
Authenticate, select one project, inspect the available tools, and begin with read-only requests.
Claude can inspect database schemas, explain SQL, diagnose logs, and draft migrations with live project context.
Treat every write or DDL call as an operational change that needs review, a rollback plan, and least privilege.
Supabase MCP 通过模型上下文协议，向 Claude Code 暴露经过授权的项目工具。
先完成认证并限定到单个项目，检查可用工具，再从只读请求开始。
Claude 可结合实时项目上下文检查数据库模式、解释 SQL、诊断日志并起草迁移。
任何写入或 DDL 调用都属于运维变更，需要人工审核、回滚预案与最小权限。
Use Supabase MCP as a deliberately small tool surface. Bind it to one development project, start read-only, and choose feature groups from the job rather than enabling the default set without review. Documentation search and schema inspection need far less authority than deploying an Edge Function or managing a database branch. After connection, verify the selected groups and run a harmless request before handing Claude a real task.
应把 Supabase MCP 当作刻意缩小的工具面：绑定单个开发项目，从只读开始，再根据任务选择功能组，而不是未经审查就开放默认集合。搜索文档和检查结构所需权限，远低于部署 Edge Function 或管理数据库分支。连接后先核对实际工具组，并完成无副作用请求，再让 Claude 处理真实任务。
Set up Supabase MCP in Claude Code在 Claude Code 中配置 Supabase MCP
Use the current Supabase MCP guide to generate a project-scoped remote HTTP URL, add it to Claude Code, and authenticate from a regular terminal. The hosted endpoint supports OAuth, so routine interactive setup does not require a personal access token.
使用当前 Supabase MCP 指南生成限定项目的远程 HTTP 地址，添加到 Claude Code，并从普通终端完成授权。托管端点支持 OAuth，因此日常交互式接入不需要个人访问令牌。
Run the generated claude mcp add command with project scope and HTTP transport. The server URL should include the intended project_ref.
Run /mcp in Claude Code, select the Supabase server, and choose Authenticate. Normal interactive setup no longer requires a personal access token.
Add read_only=true for read-only database access and enable only the feature groups needed for the task.
Ask which tables exist using MCP tools. Confirm the project identity before requesting SQL execution or migrations.
Save the selected scope, URL parameters, enabled groups, authorization owner, test prompt, expected project, and verification date with the repository's operational notes. Never record OAuth tokens or secrets.
运行生成的 claude mcp add 命令，采用项目级作用域与 HTTP 传输；服务器地址应包含目标 project_ref。
在 Claude Code 中运行 /mcp，选择 Supabase 服务器并执行认证。常规交互式配置已不再需要个人访问令牌。
加入 read_only=true 以只读方式访问数据库，并且只启用当前任务所需的功能组。
要求 Claude 使用 MCP 工具列出现有数据表，确认项目身份后，再请求执行 SQL 或迁移。
在仓库运维说明中记录所选作用域、地址参数、已启用分组、授权负责人、测试提示词、预期项目和验证日期，但不得记录 OAuth 令牌或密钥。
Select feature groups by task根据任务选择功能组
| Feature group功能组 | Enable for适用任务 | Keep disabled when何时保持关闭 | Review focus审查重点 |
|---|---|---|---|
| docs | Searching current Supabase documentation.检索当前 Supabase 文档。 | Rarely necessary to remove; it is a low-impact starting group.通常无需移除，是低影响起步分组。 | Confirm advice matches the project's product and version.确认建议符合项目产品与版本。 |
| database | Tables, extensions, migrations, SQL, and schema work.数据表、扩展、迁移、SQL 与结构工作。 | The task only needs docs or non-database context.任务只需要文档或非数据库上下文。 | Read-only state, exact SQL, target schema, and mutation risk.只读状态、准确 SQL、目标 schema 与修改风险。 |
| debugging | Service logs plus security and performance advisors.服务日志、安全与性能顾问。 | Logs may expose sensitive content and no diagnosis is needed.不需要诊断，且日志可能暴露敏感内容。 | Time window, service, redaction, and prompt injection in logs.时间范围、服务、脱敏与日志中的提示注入。 |
| development | Project URL, publishable keys, and generated TypeScript types.项目地址、可发布密钥与 TypeScript 类型生成。 | The task does not need project configuration output.任务不需要输出项目配置。 | Never confuse publishable keys with secret or service-role keys.不要把可发布密钥与 secret 或 service-role 密钥混淆。 |
| functions | Inspecting or deploying Edge Functions.检查或部署 Edge Functions。 | No function deployment is part of the approved task.获批任务不包含函数部署。 | Source diff, secrets, runtime behavior, and deployment target.源码差异、密钥、运行行为与部署目标。 |
| branching | Paid-plan development branch operations.付费计划中的开发分支操作。 | The team does not use Supabase branching for this change.团队不使用 Supabase 分支处理本次变更。 | Create, merge, reset, rebase, and delete are consequential actions.创建、合并、重置、变基与删除都属于重要操作。 |
| storage | Explicit bucket and storage configuration work.明确的存储桶与 Storage 配置工作。 | Default; storage is disabled unless deliberately selected.默认保持关闭，只有明确选择才启用。 | Bucket visibility, size limits, and configuration changes.存储桶可见性、大小限制与配置变更。 |
For schema discovery and documentation, begin with features=database,docs plus read_only=true. Add one group only when the next approved task needs it, then remove it after the task rather than leaving a broad permanent configuration.
只做结构检查与文档检索时，从 features=database,docs 和 read_only=true 开始。下一项获批任务确实需要时才增加一个分组，完成后再移除，不要长期保留过宽配置。
High-value Supabase MCP workflowsSupabase MCP 的高价值工作流
| Workflow工作流 | Prompt goal提示目标 | Output输出 | Review point审核重点 |
|---|---|---|---|
| Schema discovery数据库模式检查 | Explain tables, keys, and relationships for a feature.解释某项功能涉及的数据表、键与表间关系。 | A grounded data map.基于真实项目的数据关系图。 | Check project and schema names.核对项目与数据库模式名称。 |
| SQL diagnosisSQL 诊断 | Inspect a slow query and suggest indexes.检查慢查询并提出索引建议。 | Explanation and candidate SQL.原因说明与候选 SQL。 | Validate query plans and index write overhead.验证执行计划与索引写入开销。 |
| Migration drafting迁移起草 | Draft a reversible change for review.起草可回滚的变更供审核。 | Migration and rollback steps.迁移与回滚步骤。 | Never auto-run on production.不要在生产环境自动执行。 |
| Policy review策略审查 | Explain who can read, insert, update, and delete each row.解释谁可以读取、新增、更新和删除每一行。 | Policy matrix and uncovered paths.策略矩阵与未覆盖路径。 | Test ownership predicates and denied cases, not role names alone.测试所有权条件与拒绝情况，不能只看角色名称。 |
| Log diagnosis日志诊断 | Correlate an error within one service and time window.在一个服务和时间窗口内关联错误。 | Evidence-backed cause and next test.有证据的原因与下一项验证。 | Redact secrets and treat log text as untrusted.脱敏密钥，并把日志文本视为不可信。 |
| Type synchronization类型同步 | Regenerate types after an approved schema change.获批结构变更后重新生成类型。 | Reviewable generated type diff.可审核的生成类型差异。 | Confirm the source project and avoid unrelated churn.确认来源项目，避免无关改动。 |
Use an explicit stop condition for each workflow每种工作流都要设置明确停止条件
A good request defines where autonomy ends. Schema discovery stops after a factual map and open questions. SQL diagnosis stops after a proposed query or index plus evidence. Migration drafting stops before execution. Policy review stops before changing grants or policies. Log diagnosis stops before retrying a mutation. Type generation stops after the repository diff. These boundaries prevent a diagnostic task from silently becoming an operational change.
好的请求会明确自动化到哪里结束。结构检查在事实地图和待确认问题处停止；SQL 诊断在候选查询或索引及其证据处停止；迁移起草在执行前停止；策略审查在修改授权或策略前停止；日志诊断在重试修改操作前停止；类型生成在仓库差异处停止。明确边界可以防止诊断任务悄悄演变成运维变更。
Troubleshoot by configuration, authorization, scope, and task按配置、授权、范围与任务逐层排查
Check the Claude Code scope, repository root, .mcp.json when project-scoped, server name, and session reload. Use claude mcp list and claude mcp get supabase before changing credentials.
Run /mcp from a regular terminal, authenticate with the organization that owns the selected project, and check browser, proxy, and callback restrictions. Do not paste a PAT into a shared URL as a workaround.
Compare the requested action with features. Project scope removes account tools, storage is disabled by default, and authorization or URL changes may require a reload.
Verify project reference, organization, branch, schema, time range, and account permissions. Stop when unknown or sensitive data appears; a write is not an acceptable connection test.
Narrow the log window, query, schema, or requested operation. Before retrying a write-capable call, inspect whether the first attempt already changed state.
检查 Claude Code 作用域、仓库根目录、project 作用域下的 .mcp.json、服务名称和会话重载。修改凭据前先用 claude mcp list 与 claude mcp get supabase 查看状态。
从普通终端运行 /mcp，用目标项目所在组织完成授权，并检查浏览器、代理和回调限制。不要为了绕过问题，把 PAT 粘贴进共享地址。
把目标操作与 features 对照。项目绑定会移除账户工具，storage 默认关闭，授权或地址变化后可能还需要重新加载。
核对项目引用、组织、分支、schema、时间范围与账户权限。出现陌生或敏感数据时立即停止；不能用写入来测试连接。
缩小日志窗口、查询、schema 或操作范围。重试可写调用前，先检查第一次尝试是否已经改变状态。
Security boundaries before tool execution执行工具前先明确安全边界
Supabase MCP is designed for development and testing. Use a development project with non-production or obfuscated data, not a production database.
Keep manual approval enabled. Treat database content as untrusted because prompt injection can hide instructions inside rows returned to Claude.
It reduces database mutation but still permits authorized reads. Use synthetic or obfuscated data, avoid customer and authentication records, and narrow schemas, queries, logs, and output.
Check RLS ownership predicates, view security, function execution grants, SECURITY DEFINER, exposed schemas, migrations, and Data API grants. Developer access may not match an application's end-user restrictions.
Supabase MCP 面向开发与测试场景。应连接只含非生产数据或已脱敏数据的开发项目，不要连接生产数据库。
始终保留人工批准。数据库内容属于不可信输入，因为提示注入指令可能隐藏在 Claude 读取的记录中。
它能减少数据库修改，但仍允许授权读取。应使用模拟或脱敏数据，避开客户与认证记录，并缩小 schema、查询、日志和输出范围。
检查 RLS 所有权条件、视图安全、函数执行授权、SECURITY DEFINER、暴露 schema、迁移与 Data API 授权。开发者访问不一定符合应用终端用户的限制。
Where QVeris fits beside Supabase MCPQVeris 如何与 Supabase MCP 配合
Supabase MCP gives Claude Code focused access to one backend platform. Current QVeris Tool and Provider searches return no exact Supabase record, so use QVeris Docs and the Playground for separate external capabilities rather than assuming a direct integration.
Supabase MCP 让 Claude Code 专注访问一个后端平台。当前 QVeris Tool 与 Provider 搜索没有返回完全对应的 Supabase 条目。如果任务还需要其他外部能力，可以查阅 QVeris 文档，并在 Playground 中继续寻找，不要假设已经存在直接集成。
- Keep Supabase MCP for database schemas, SQL, logs, and project operations inside Supabase.
- Use QVeris discovery when the workflow needs trusted tools or data outside that project boundary.
- Inspect the returned provider, schema, constraints, and cost, then validate the result before writing it to Supabase.
- Supabase MCP 负责 Supabase 内部的数据库模式、SQL、日志与项目操作。
- 工作流需要项目边界之外的可信工具或数据时，再使用 QVeris 发现能力。
- 检查检索结果的供应商、参数结构、约束与成本，外部结果写入 Supabase 前先完成校验。
FAQ常见问题
No. Supabase recommends a development project with non-production or obfuscated data because the MCP server is designed for development and testing.
The available tool set may support database changes, but you should request a preview, review the SQL, test rollback, and approve execution explicitly.
For schema and documentation work, start with database,docs plus read-only. Add debugging, development, functions, branching, or storage only for an approved task.
Adding project_ref intentionally disables account-management tools because the connection is restricted to one project.
The storage feature group is disabled by default. Enable it only for a specific reviewed storage configuration task.
No. It restricts writes, not authorized reads or disclosure through model context. Use non-production, synthetic, or properly obfuscated data.
不应该。Supabase 建议使用只含非生产数据或已脱敏数据的开发项目，因为 MCP 服务器面向开发与测试场景。
可用工具可能支持数据库变更，但应先预览并审核 SQL，测试回滚流程，再明确批准执行。
结构和文档任务从 database,docs 加只读开始。debugging、development、functions、branching 或 storage 只为获批任务开放。
加入 project_ref 后会有意禁用账户管理工具，因为连接已经限定到单个项目。
storage 功能组默认关闭，只有处理明确且已审查的存储配置任务时才启用。
不能。它限制写入，但不限制已授权读取或模型上下文泄露。应使用非生产、模拟或妥善脱敏数据。
References and next steps参考资料与下一步
Supabase MCP guide
Supabase MCP repository
Claude Code MCP documentation