Supabase MCP Server: Setup Guide, Use Cases & Limitations

What Is Supabase MCP Server?

Supabase MCP Server exposes your Supabase projects to Claude via the Model Context Protocol, enabling database queries, schema inspection, table management, and storage access directly from your AI assistant. It is maintained by the Supabase community under the supabase-community GitHub organization.

Quick Facts

What You Can Do With It

• Database queries: Run SQL queries against your Supabase Postgres database from within a Claude conversation.
• Table management: Create, alter, or inspect tables and columns without leaving your Claude session.
• Schema inspection: Retrieve schema details — column types, constraints, indexes — to inform migrations or debugging.
• Auth inspection: Review your project’s auth configuration and user data structures.
• Storage access: Browse and interact with Supabase Storage buckets and objects.

How to Set It Up

Prerequisites: Node.js 18+ and a Supabase project with a valid service role key or personal access token.

Step 1 — Test the server locally

npx @supabase/mcp-server-supabase
This confirms the package resolves correctly before wiring it into a client.

**Step 2 — Configure Claude Desktop**

Add the server to your `claude_desktop_config.json` (typically at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["@supabase/mcp-server-supabase"],
      "env": {
        "SUPABASE_URL": "https://your-project-ref.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
      }
    }
  }
}

Step 3 — Configure Claude Code

For Claude Code, add the equivalent block to .claude/mcp.json at your project root:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["@supabase/mcp-server-supabase"],
      "env": {
        "SUPABASE_URL": "https://your-project-ref.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
      }
    }
  }
}

Restart Claude after editing config files for changes to take effect.

Works Best With

This server is documented as compatible with Claude Code and Claude Desktop. Claude Code is the stronger pairing for development workflows — you can query schema, draft migrations, and apply changes without context switching. Claude Desktop works well for exploratory queries and one-off inspection tasks.

Known Limitations

• Service role key exposure: The config requires a SUPABASE_SERVICE_ROLE_KEY, which bypasses Row Level Security. Never commit this config file to version control.
• No RLS enforcement: Because queries typically run under the service role, your normal RLS policies do not apply. Be deliberate about what Claude can read or modify.
• Mutation risk: Table management and migration tools can make destructive changes. Review any generated SQL before confirming execution.
• Rate limits: Supabase project-level API rate limits still apply. Heavy query loops inside long Claude sessions may hit throttling.
• Self-hosted Supabase: Compatibility with self-hosted instances is not explicitly documented — verify your endpoint and key configuration against the upstream README.

Community Resources

• GitHub Repository — primary source for setup docs, open issues, and changelogs
• GitHub Issues — report bugs or check known problems before opening a new ticket
• Supabase Discord — #help and #ai channels are active; search for “MCP” to find relevant threads
• r/Supabase — community discussion including MCP integration experiences