Supabase MCP Integration

Supabase MCP Integration is an MCP server that provides AI assistants with comprehensive access to Supabase's backend-as-a-service platform, including PostgreSQL database queries, authentication management, storage operations, and real-time capabilities. This MCP bridge enables language models to interact with your Supabase project's full feature set through conversational commands, supporting database exploration, user management, file operations, and edge function invocation.

When to Use This MCP Server

Connect this server when...

• Your application backend runs on Supabase and you want AI-assisted database queries, schema exploration, and data analysis
• You need to manage Supabase authentication users, roles, and access policies through natural language commands
• Your workflow involves Supabase Storage for file management and you want AI assistance with bucket operations
• You are developing Supabase Edge Functions and need AI help with function deployment and testing
• You want to set up Row Level Security policies, database triggers, and other Supabase-specific configurations with AI guidance

Consider alternatives when...

• Your backend uses Firebase, AWS Amplify, or another BaaS platform with its own MCP server
• You only need direct PostgreSQL access without Supabase-specific features (use a generic database MCP)
• You require real-time subscription management that goes beyond the MCP request-response model

Quick Start

Copy
# .mcp.json configuration
{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server"],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_KEY": "your-service-role-key"
      }
    }
  }
}

Connection setup:

1. Navigate to your Supabase project settings at app.supabase.com
2. Copy your project URL and service role key from Settings > API
3. Add the configuration above to your .mcp.json file with your credentials
4. Restart your MCP client to connect to your Supabase project

Example tool usage:

# Query the database
> Show me all users who signed up in the last 7 days with their subscription status

# Manage storage
> List all files in the "avatars" storage bucket

# Inspect RLS policies
> What Row Level Security policies are configured on the orders table?

Core Concepts

Concept	Purpose	Details
PostgreSQL Database	Data storage	Full PostgreSQL database with tables, views, functions, and extensions accessible through SQL
Authentication	User management	Supabase Auth for managing users, sessions, OAuth providers, and role-based access control
Storage	File management	Object storage with buckets, file uploads, and access policies for managing application assets
Edge Functions	Serverless compute	Deno-based serverless functions deployed at the edge for custom API endpoints and webhooks
Row Level Security	Access control	PostgreSQL policies that control which rows users can access based on their authentication status

Architecture:

+------------------+       +------------------+       +------------------+
|  Supabase        |       |  Supabase MCP    |       |  AI Assistant    |
|  Project         |<----->|  Server (npx)    |<----->|  (Claude, etc.)  |
|  DB/Auth/Storage | HTTPS |  stdio transport  | stdio |                  |
+------------------+       +------------------+       +------------------+
        |
        v
+------------------------------------------------------+
|  Database > Auth > Storage > Functions > RLS           |
+------------------------------------------------------+

Configuration

Parameter	Type	Default	Description
SUPABASE_URL	string	(required)	Your Supabase project URL (https://your-project.supabase.co)
SUPABASE_SERVICE_KEY	string	(required)	Service role key with full access (bypasses Row Level Security)
read_only	boolean	false	Restrict database operations to read-only queries
default_schema	string	public	Default PostgreSQL schema for table operations
query_timeout	integer	30000	Maximum query execution time in milliseconds

Best Practices

1. Use the service role key carefully. The service role key bypasses Row Level Security policies and has full database access. This is necessary for the MCP server to inspect RLS policies and manage all data, but it means the AI has unrestricted access. Enable read-only mode for production databases when write access is not needed.

2. Inspect RLS policies before modifying data. Before making data changes through the MCP server, ask the AI to inspect existing Row Level Security policies. Understanding the security model ensures you do not accidentally expose data or break access controls when modifying table structures.

3. Use the database schema exploration tools first. Before writing queries, have the AI explore tables, columns, and relationships. Supabase projects can have complex schemas with many tables across multiple schemas. Understanding the structure first produces better queries.

4. Manage authentication users through the proper API. Rather than directly modifying the auth.users table, use the Supabase Auth management tools provided by the MCP server. Direct table modifications can break authentication flows and session management.

5. Test Edge Functions in a development environment. When deploying or modifying Edge Functions through the MCP server, test in a development Supabase project first. Edge Functions affect your application's API behavior, and untested changes can break production endpoints.

Common Issues

"Invalid API key" when connecting. Ensure you are using the service role key (starts with eyJ...) and not the anon/public key. The service role key is found in Settings > API > Project API keys > service_role. The anon key has restricted access that may not support all MCP operations.

Queries fail with "permission denied" despite using service key. Some operations require superuser privileges that even the service role key does not have. Database extensions, certain system catalog queries, and some DDL operations may require direct database access through the Supabase SQL Editor or a direct PostgreSQL connection.

Storage operations return "bucket not found". Verify the bucket name is spelled correctly and exists in your Supabase project. Buckets are case-sensitive. Navigate to Storage in your Supabase dashboard to confirm available buckets and their names.