Claude Code 连 Supabase MCP：用 project 范围的 .mcp.json 锁定单一项目、只读，再用 OAuth 登录

在 Claude Code 里接上 Supabase MCP，Claude 就能直接查数据表、看日志、应用 migration。方便的同时也很危险：一个没锁范围的 MCP，可以看到你账号下所有组织和项目。我在 Oracle Cloud 的 VM 上通过 SSH 运行 Claude Code，做法是把 Supabase MCP 设成项目范围（写在项目的 .mcp.json），网址锁定单一项目、只读，再用 OAuth 登录。

先说结论：用 claude mcp add --scope project --transport http 添加 Supabase 的官方网址 https://mcp.supabase.com/mcp，自己在网址后面加上 project_ref 和 read_only=true；接着用 /mcp 或 claude mcp login supabase 完成 OAuth。登录后、写入任何数据之前，先确认它连到的是哪个项目。

本文根据 2026 年 10 月 15 日查阅的 Claude Code 与 Supabase 官方文档整理，命令和参数可能随版本改变，使用前请以官方文档为准。

先选范围：local、project、user 有什么区别

Claude Code 的 MCP 设置有三种范围（Claude Code 官方文档）：

范围	在哪里生效	会和别人共用吗	保存在哪里
local（默认）	只有当前项目	不会	`~/.claude.json` 里这个项目的设置
project	只有当前项目	会，随版本控制共享	项目根目录的 `.mcp.json`
user	你所有的项目	不会	`~/.claude.json`

我选 project 范围，原因有两个：

设置看得到、改得了：.mcp.json 是项目里的一个文件，网址里有没有 project_ref、read_only，打开就知道。
只在这个项目生效：换到别的项目文件夹，这个 Supabase 连接就不会出现。

同一个名字的服务器出现在多个范围时，优先顺序是 local、project、user，然后才是插件和 claude.ai 连接器；Claude Code 会整条使用优先的那一个，不会合并字段。

添加 Supabase MCP：官方命令再加上 project_ref 与 read_only

Supabase 官方文档给 Claude Code 的命令是（Supabase 官方文档）：

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

这个命令没有锁定项目。我会在网址后面加上两个参数：

claude mcp add --scope project --transport http supabase \
  "https://mcp.supabase.com/mcp?project_ref=<项目代码>&read_only=true"

执行后，项目根目录的 .mcp.json 会是这样：

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp?project_ref=<项目代码>&read_only=true"
    }
  }
}

<项目代码> 是 Supabase 项目的 Project ID，在项目的设置页可以找到。

三个网址参数

参数	作用
`project_ref=<项目代码>`	只能操作这一个项目；列出项目、创建项目这类账号级别的工具会关闭
`read_only=true`	查询用只读的 Postgres 用户执行
`features=<工具组>`	只开放列出的工具组，用逗号分隔，例如 `features=database,docs`

工具组包括 Database（查数据表、执行 SQL、应用 migration）、Debugging（查日志、安全建议）、Development（项目网址、公开密钥、生成 TypeScript 类型）、Edge Functions、Docs、Branching，以及默认关闭的 Storage（Supabase 工具清单）。

我的做法是平时用 read_only=true；真的要应用 migration 的那一次，才另外处理，而且先在开发分支或测试项目上试。

第一次启用：批准项目范围的服务器

.mcp.json 可能是别人放进 repo 的，所以 Claude Code 在交互模式下，第一次使用项目范围的服务器前会先问你是否批准。还没批准时，claude mcp list 会显示 Pending approval。

批准或拒绝的结果，记在项目的 .claude/settings.local.json。
想重新选择：claude mcp reset-project-choices。
要注意的例外：用 claude -p、Agent SDK 或云端会话运行时不会询问，项目范围的服务器会直接加载。不想让它在这些情况下加载，要另外用 disabledMcpjsonServers 这类设置排除（Claude Code 设置说明）。

用 OAuth 登录 Supabase

Supabase 的托管 MCP 支持 OAuth，不用自己创建访问令牌。

**在 Claude Code 里：**执行 /mcp，选 supabase，再选 Authenticate。浏览器会打开 Supabase 的授权页，登录后选择组织。Supabase 文档建议在普通终端里操作，不要在 IDE 插件里。

在 shell 里：

claude mcp login supabase

登录成功后，claude mcp list 会显示 Connected；需要登录时显示 Needs authentication。官方文档说明令牌会安全保存、自动更新。

通过 SSH 在远程主机登录

我的 Claude Code 运行在 Oracle Cloud 的 VM 上，我从 Mac 用 SSH 连进去，主机上没有浏览器。官方文档的做法（Claude Code 官方文档）：

用 ssh -t 连接，执行 claude mcp login supabase。检测不到浏览器时，它会打印授权网址；想强制使用这个流程可以加 --no-browser。
把网址粘贴到 Mac 的浏览器打开，登录 Supabase、选组织。
授权后浏览器会跳到 http://localhost:<端口>/callback，因为那是 VM 的 localhost，Mac 上会打不开。这没关系：把浏览器地址栏上完整的 callback 网址复制下来，粘贴回 Claude Code 等待输入的地方。

端口默认每次随机，要固定可以在添加服务器时用 --callback-port。

授权网址在终端里复制不了、屏幕上写着 Sent via OSC 52 却没有进剪贴板，是另一个问题，做法我写在〈Claude Code OAuth 网址复制不了怎么办〉；要用 SSH 端口转发处理 callback，也在那篇。

确认连到哪个项目：写入数据前一定要做

登录时选的是组织，网址里的 project_ref 才决定项目。我会做两个确认：

看设置：claude mcp get supabase 会显示设置的网址和范围，确认 project_ref 是你要的项目、read_only=true 还在。
问 MCP 本身：让 Claude 调用 Supabase MCP 的 get_project_url 工具，它会返回项目的 API 网址，网址里就有项目代码，和你预期的比对。

这是我自己的检查习惯，官方文档没有规定一定要这样做；但两个项目的数据表长得很像时，搞错对象的代价很高。

/mcp 里同时出现两个 Supabase

如果你在 claude.ai 账号添加过 Supabase 连接器，/mcp 里可能会同时看到 supabase 和 claude.ai Supabase。官方文档说明，claude.ai 的连接器会自动带进 Claude Code，授权在 claude.ai 那一端处理（Claude Code 官方文档）。

两者的区别：

	项目范围的 `supabase`	`claude.ai Supabase`
设置在哪里	项目的 `.mcp.json`	claude.ai 账号的连接器设置
能否锁定单一项目、只读	能，网址参数看得到	取决于你在 claude.ai 的授权，项目里看不到设置
在哪里授权	在这台主机上用 OAuth 登录	claude.ai 网页

在我的环境里，claude.ai Supabase 可能连到别的组织，不一定是我要操作的项目。所以要在项目里操作数据库时，我只用项目范围的那一个。不需要 claude.ai 的连接器时，可以在 /mcp 里把它关掉，或在设置文件加 "disableClaudeAiConnectors": true（Claude Code 设置说明）。

安全设置：Supabase 官方的提醒

Supabase 文档特别提醒 prompt injection：数据表里的文字（例如一条客服留言）可能夹带指令，诱导 AI 执行你没让它做的事。查询结果虽然会加上防护说明，但官方也写明“不是万无一失”（Supabase 官方文档）。官方建议：

交互使用时，保留每次工具调用的手动确认。
只在任务确实需要生产环境数据时，才连生产项目。
使用只读模式、锁定单一项目、只开需要的工具组。
数据库结构的变更先在开发分支上试。
不要把这个 MCP 给终端用户使用，它用的是你开发者账号的权限。

移除或重新登录

想做的事	做法
重新登录	`/mcp` → 选服务器 → Clear authentication → Authenticate；或 `claude mcp logout supabase` 再 `claude mcp login supabase`
令牌过期被拒	`/mcp` 会提示 Re-authenticate
暂时停用	在 `/mcp` 里关掉这个服务器
完全移除	`claude mcp remove supabase --scope project`，会一并删除它保存的 OAuth 令牌和客户端注册

Oracle Cloud VM 怎么装 Claude Code、怎么让它常驻，见〈Oracle Cloud 运行 Claude Code Remote Control 常驻教程〉。

常见问题

Claude Code 连 Supabase MCP 要用哪个命令？

Supabase 官方文档给的命令是 claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp"。它会在项目根目录写入 .mcp.json。官方命令没有带 project_ref；要锁定单一项目和只读，自己在网址后面加上 ?project_ref=你的项目代码&read_only=true。

MCP 的 local、project、user 范围有什么区别？

根据 Claude Code 官方文档：local 是默认值，只在当前项目生效、只有你自己用，保存在 ~/.claude.json；project 写在项目根目录的 .mcp.json，可以纳入版本控制、与团队共用；user 对你所有项目生效，也保存在 ~/.claude.json。同名服务器出现在多个范围时，local 优先，其次是 project、user，最后才是插件和 claude.ai 连接器。

在通过 SSH 连接的主机上，Supabase MCP 的 OAuth 怎么登录？

可以在 Claude Code 里用 /mcp 选 supabase 再选 Authenticate，或在 shell 执行 claude mcp login supabase。没有浏览器的环境会打印授权网址，在自己电脑的浏览器打开、登录 Supabase，再把浏览器地址栏上完整的 callback 网址粘贴回 Claude Code。交互式粘贴要用 ssh -t 连接。

怎么确认 Supabase MCP 连到的是哪个项目？

先看 .mcp.json 或 claude mcp get supabase 显示的网址，project_ref 参数就是项目代码。也可以让 Claude 调用 Supabase MCP 的 get_project_url 工具，它会返回项目的 API 网址，网址里有项目代码。执行会写入数据的操作之前，先确认这一步。

/mcp 里同时出现 supabase 和 claude.ai Supabase，该用哪一个？

claude.ai Supabase 是你在 claude.ai 账号添加的连接器，Claude Code 会自动带进来，授权和设置都在 claude.ai 那一端，连到哪个组织要看你当时在 claude.ai 授权了什么。项目范围的 supabase 是写在 .mcp.json 里的设置，网址参数看得到、能锁定单一项目。要在项目里操作数据库，我用项目范围的 supabase。

怎么移除或重新登录 Supabase MCP？

重新登录：在 /mcp 选服务器，用 Clear authentication 清除，再 Authenticate；或在 shell 执行 claude mcp logout supabase 再 claude mcp login supabase。完全移除：claude mcp remove supabase --scope project，官方文档说明这也会删除它保存的 OAuth 令牌和客户端注册。