Open Claude Code in a project folder and its Supabase MCP connects to exactly that project — on the correct account, read-only by default. No more logging out to switch. Tokens stay encrypted in your OS keychain and never touch disk.
Free & open source · An unofficial community project, not affiliated with Supabase or Anthropic
The default Supabase MCP uses OAuth and connects one organization at a time. With a personal account and a company account across several organizations, you end up logging out and back in to switch — and a session open in a company project can still be pointed at your personal database.
Log out, log back in, hope the session is on the right account. One wrong window and you run a query against the wrong database.
Each directory is pinned to one project on one account. Open Claude Code there and the correct database connects automatically — verified live.
A Personal Access Token is per account, not per organization — it reaches every org and project in that account. A personal and a company login are just two tokens.
supa-mcp link writes a .mcp.json that pins one project_ref and names its account. Claude Code auto-loads it from the folder it starts in.
At each connection Claude Code runs supa-mcp headers, which reads the token from the Keychain in memory. Nothing secret is ever written to .mcp.json.
| Default Supabase MCP | supa-mcp | |
|---|---|---|
| Accounts at once | One org via OAuth | Every account & org, side by side |
| Switching projects | Log out, log back in | Automatic — pinned per directory |
| Wrong-account risk | A session can point at the wrong DB | Live guard flags a mislinked directory |
| Token storage | OAuth session | OS keychain, never on disk |
| Default access | Read-write | Read-only unless you opt in |
| Config in the repo | — | .mcp.json holds no secret, safe to commit |
Requires jq and curl, plus the OS keychain — security on macOS (built in) or secret-tool (libsecret) on Linux. Install jq with brew install jq or apt install jq.
This adds the CLI, the /supa-* slash commands, and the skill. Then put the CLI on your PATH.
/plugin marketplace add im-shubhamsharma/supabase-mcp /plugin install supa-mcp@supa-mcp supa-mcp install
Create a token at supabase.com/dashboard/account/tokens. The prompt hides your input and stores the token straight into the Keychain — never paste it into a chat.
supa-mcp account add personal supa-mcp account add company
See what a token can reach, then pin this folder to the right project. Read-only by default — add --write only when you mean it.
# list the orgs & projects this account can see supa-mcp whoami company # in your project folder, pin it — by ref, or by name cd ~/work/company-app supa-mcp link --account company --project-ref abcd1234 supa-mcp link --account company --project company-app
Or skip steps 2–3 entirely with supa-mcp init — it prompts for an account (if you don't have one) and links the directory in one pass.
Start a fresh session in that directory. Accept the workspace-trust prompt and the one-time Keychain prompt (choose Always Allow). The Supabase MCP is now connected to that exact project. Inside Claude Code, drive everything with /supa-init, /supa-add, /supa-link, /supa-switch, /supa-status, /supa-list, /supa-branches, /supa-open, and /supa-unlink.
The CLI is supa-mcp. Run supa-mcp doctor anytime to check dependencies, PATH, and the current directory. Project lists are cached ~5 minutes per account — pass --refresh for a live lookup.
| Command | Purpose |
|---|---|
init | Guided setup: add an account (if needed) and link this directory. |
account add <name> | Store a Personal Access Token in the Keychain (hidden prompt, validated before storing). |
account list | List registered accounts and whether each token is present. |
account remove <name> | Delete an account and its token. |
whoami <account> | Show the orgs and projects a token can see. |
projects <account> | List an account's projects (name, ref, org). |
branches <account> <ref> | List a project's Supabase branches. |
link --account <n> (--project-ref <ref> | --project <name>) | Write ./.mcp.json for this directory. --write to allow writes. |
switch (--project-ref <ref> | --project <name> | --branch <name>) | Re-point this directory's binding. |
status | Show and live-verify this directory's binding. |
list --verify | Every linked directory on this machine, live-checked. |
open | Open this directory's project in the Supabase dashboard. |
unlink | Remove the server from ./.mcp.json (deletes the file once empty). |
export / import | Move accounts + links between machines (no secrets). |
doctor | Check dependencies, keychain backend, and token health. |
supa-mcp), encrypted at rest..mcp.json holds only a project_ref and a helper command — no secret. The registry, env, and git never hold a token.read_only=true. Writes require an explicit --write at link time.supa-mcp status checks live that the pinned project really belongs to the linked account, so you catch a mislinked directory before running anything.account add checks a token against the Supabase API first — an invalid or expired token never lands in the Keychain unless you pass --force.Star it, read the source, or open an issue — contributions welcome, including Linux and Windows Keychain backends.