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 權杖和用戶端註冊。