Supabase MCP Local Project Configuration

Why Local (Not Global)

• Each project has its own Supabase database
• Prevents accidentally running queries on wrong database
• Project ref scopes access to specific project

Setup Steps

1. Add token to project .env.local

Copy SUPABASE_ACCESS_TOKEN from ~/.env.local to your project .env.local, or get a new token from https://supabase.com/dashboard/account/tokens

2. Create .mcp.json in project root

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REF",
      "headers": {
        "Authorization": "Bearer ${SUPABASE_ACCESS_TOKEN}"
      }
    }
  }
}

3. Get your Project Ref from user

Project Ref (YOUR_PROJECT_REF):

• Go to Supabase Dashboard → Your Project → Settings → General
• Copy the "Reference ID" (e.g., xyzexampleref12345678)
• Replace YOUR_PROJECT_REF in the URL above

4. Restart Claude Code

After creating/editing .mcp.json, you must:

• Type exit in Claude Code
• Run claude again (or claude --resume to continue conversation)

5. Verify it works

Ask Claude to run:

mcp__supabase__list_tables

If configured correctly, it will return your database tables.

Troubleshooting

MCP not loading:

• Check .mcp.json is in project root
• Verify JSON syntax is valid
• Restart Claude Code (exit + claude)

Authentication error:

• Check project .env.local has SUPABASE_ACCESS_TOKEN
• Token must start with sbp_

Wrong database:

• Verify project_ref matches your project's Reference ID