Connected Supabase Module

Integrate Claude Code with the Supabase platform for managing databases, authentication, storage, edge functions, and real-time subscriptions through MCP.

When to Use This MCP Server

Connect this server when you need to:

• Manage Supabase projects including database tables, RLS policies, authentication providers, and storage buckets directly from Claude Code
• Query your Supabase PostgreSQL database, create or modify tables, and test Row Level Security policies during application development
• Deploy and test Supabase Edge Functions, manage API keys, and configure real-time subscriptions as part of your full-stack workflow

Consider alternatives when:

• You are working with a plain PostgreSQL database not hosted on Supabase, where the PostgreSQL Integration MCP server provides direct database access
• Your project only needs Supabase client-side SDK interactions and does not require server-side management or administrative operations

Quick Start

Configuration

Copy
name: connected-supabase-module
type: mcp
category: database

Example Connection

Copy
claude mcp:connect connected-supabase-module

Available Tools

query:              Execute SQL queries against the Supabase PostgreSQL database
manage-tables:      Create, alter, or drop tables with column definitions and constraints
manage-rls:         Create, update, or delete Row Level Security policies on tables
manage-storage:     Create buckets, upload files, and configure storage access policies
manage-auth:        Configure authentication providers, manage users, and inspect sessions

Core Concepts

Supabase Platform Overview

Aspect	Details
Transport	stdio-based MCP server connecting via Supabase Management API and database
Database	Managed PostgreSQL with automatic API generation via PostgREST
Authentication	Built-in auth with email, OAuth, phone, and magic link providers
Storage	S3-compatible object storage with RLS-protected access policies
Real-time	WebSocket-based real-time subscriptions for database change events

Supabase MCP Integration Architecture

Claude Code IDE
    |
    v
[MCP Client] --stdio--> [Supabase MCP Server]
                              |
                    +---------+---------+
                    |         |         |
                    v         v         v
              [Database] [Auth API] [Storage]
              PostgreSQL   GoTrue    S3-compat
                    |         |         |
                    v         v         v
              [Supabase Project Instance]
                    |
                    v
              [Edge Functions]
              (Deno Runtime)

Configuration

Parameter	Type	Default	Description
SUPABASE_URL	string	required	Your Supabase project URL in the format https://xxxx.supabase.co
SUPABASE_SERVICE_KEY	string	required	Service role key for administrative access bypassing RLS
SUPABASE_ANON_KEY	string	optional	Anonymous key for testing RLS-protected operations
project_ref	string	auto-detected	Supabase project reference ID for Management API calls
default_schema	string	public	Default database schema for table operations

Best Practices

1. Use Service Key Only for Administration - The service role key bypasses Row Level Security. Use it for schema management and administrative tasks, but switch to the anon key when testing application-level queries to verify your RLS policies work correctly.

2. Test RLS Policies During Development - Use the manage-rls tool to create and test Row Level Security policies alongside your application code. Verifying policies early prevents security gaps that are harder to catch after deployment.

3. Organize Storage with Bucket Policies - Create separate storage buckets for different content types (avatars, documents, uploads) and apply appropriate access policies to each. This separation simplifies access control and makes it easier to manage storage lifecycle rules.

4. Version Your Edge Functions - When deploying Edge Functions through the MCP server, maintain version discipline by testing functions locally before deploying. Use the query tool to verify that database triggers and function invocations work as expected.

5. Keep Secrets in Environment Variables - Never hardcode Supabase keys in MCP configuration files. Store SUPABASE_URL, SUPABASE_SERVICE_KEY, and SUPABASE_ANON_KEY as environment variables in your shell profile or a local .env file excluded from version control.

Common Issues

1. RLS Policy Blocks Expected Queries - When queries return empty results despite data existing, check that the correct key (service vs anon) is being used. Service key bypasses RLS; anon key respects all policies. Use manage-rls to inspect active policies on the affected table.

2. Edge Function Deployment Timeout - Large Edge Functions or those with many dependencies may exceed deployment timeouts. Reduce bundle size by minimizing imports and using Deno-native APIs where possible.

3. Storage Upload Returns 403 Forbidden - Verify that the storage bucket's access policy allows the operation. Public buckets allow unauthenticated reads but still require authentication for uploads unless explicitly configured otherwise.