Supabase MCP Server

A comprehensive Model Context Protocol server for self-hosted Supabase instances

I built this MCP server for my own needs when working with self-hosted Supabase instances and Claude. Figured it might be useful for others, so here it is! 🚀

This server provides 42 tools covering everything from database operations to edge functions - basically everything you can do in the Supabase dashboard, but through Claude.

What's This About?

When you're running your own Supabase instance and want Claude to help you manage it, the existing tools are pretty limited. So I built this comprehensive MCP server that gives Claude full access to:

• 🔐 Authentication - User signup, login, session management

• 📊 Database - Full CRUD operations with smart query building

• 🔄 Realtime - Subscribe to changes, create channels, broadcast messages

• 📁 Storage - File upload, download, bucket management

• 🛡️ Security - Row Level Security (RLS) policies and permissions

• ⚡ Edge Functions - Deploy, invoke, and manage serverless functions

• 🗂️ Schema - Explore tables, columns, and relationships

• 🔍 SQL - Raw SQL execution with smart fallbacks

Related MCP server: Supabase MCP Server

Features

• Complete Dashboard Parity - Pretty much everything you can do in Supabase Studio

• Smart Error Handling - Helpful troubleshooting tips when things go wrong

• Multiple Fallbacks - If one approach fails, it tries others automatically

• Built-in Edge Functions - Local Node.js serverless handler for testing

• Enhanced SQL - Client-side aggregation when raw SQL isn't available

• TypeScript - Fully typed for better development experience

Quick Start

1. Install Dependencies

npm install

2. Build the Project

npm run build

3. Configure Claude Desktop

Copy mcp.json.example to your Claude Desktop config and update it:

{
  "mcpServers": {
    "supabase": {
      "command": "node",
      "args": ["/path/to/self-hosted-supabase-mcp/dist/index.js"],
      "env": {
        "SUPABASE_URL": "http://localhost:54321",
        "SUPABASE_ANON_KEY": "your_anon_key_here",
        "SUPABASE_SERVICE_ROLE_KEY": "your_service_role_key_here"
      }
    }
  }
}

4. Restart Claude Desktop

And you're good to go! Claude will now have access to all 42 Supabase tools.

Available Tools

Connection & Auth (5 tools)

• connection_test - Test your Supabase connection

• auth_signup - Register new users

• auth_login - Authenticate users

• auth_get_user - Get current user info

• auth_logout - Sign out users

Database Operations (6 tools)

• db_select - Query data with filters and sorting

• db_insert - Insert new records

• db_update - Update existing records

• db_delete - Delete records

• db_upsert - Insert or update (with conflict handling)

• db_count - Count records with filters

Schema Exploration (3 tools)

• schema_get_tables - List all tables

• schema_get_columns - Get column information

• schema_get_relations - Explore foreign key relationships

Storage Management (6 tools)

• storage_list_buckets - List storage buckets

• storage_create_bucket - Create new buckets

• storage_delete_bucket - Remove buckets

• storage_list_files - Browse files

• storage_upload_file - Upload files (base64)

• storage_download_file - Download files

• storage_delete_file - Remove files

• storage_get_public_url - Get public file URLs

Edge Functions (4 tools)

• edge_list_functions - List deployed functions

• edge_deploy_function - Deploy new functions

• edge_invoke_function - Execute functions

• edge_remove_function - Clean up functions

Realtime (3 tools)

• realtime_subscribe - Listen to database changes

• realtime_channel_create - Set up broadcast channels

• realtime_broadcast - Send messages to channels

SQL & Advanced Queries (6 tools)

• sql_execute - Run SQL queries with smart parsing

• sql_call_rpc - Execute stored procedures

• sql_aggregate - COUNT, SUM, AVG, MIN, MAX operations

• sql_execute_raw - Raw SQL with multiple fallback methods

• sql_aggregate_enhanced - Advanced aggregation with client-side processing

• sql_analyze_table - Get detailed table statistics

Security & RLS (6 tools)

• security_check_rls_status - Check Row Level Security status

• security_enable_rls - Enable RLS on tables

• security_disable_rls - Disable RLS

• security_create_policy - Create RLS policies

• security_list_policies - List existing policies

• security_drop_policy - Remove policies

• security_test_policy - Test policy effectiveness

What Makes This Different?

Most MCP servers for databases are pretty basic. This one is different because:

1. It actually works with self-hosted Supabase - Many tools assume cloud Supabase

2. Comprehensive coverage - 42 tools covering every major Supabase feature

3. Smart fallbacks - If the direct approach fails, it tries other methods

4. Built-in edge functions - Local Node.js serverless handler for testing

5. Real troubleshooting help - When something breaks, it tells you how to fix it

Configuration Options

You can customize the server through environment variables:

• SUPABASE_URL - Your Supabase instance URL

• SUPABASE_ANON_KEY - Anonymous/public key

• SUPABASE_SERVICE_ROLE_KEY - Service role key (for admin operations)

• MCP_SERVER_NAME - Custom server name (default: "supabase-mcp-server")

• MCP_SERVER_VERSION - Custom version (default: "1.0.0")

Development

# Install dependencies
npm install

# Build for production
npm run build

# Development mode (watch for changes)
npm run dev

# Clean build artifacts
npm run clean

Troubleshooting

Connection Issues

• Make sure your Supabase instance is running

• Check if the URL and keys are correct

• Verify network connectivity to your Supabase instance

Authentication Problems

• Email confirmation might be enabled but SMTP not configured

• Try disabling email confirmation in Supabase Dashboard

• Check if the user already exists

SQL/Database Issues

• Some advanced SQL features require service role key

• RLS policies might be blocking access

• Use db_select instead of raw SQL for better compatibility

Contributing

Found a bug or want to add a feature? Feel free to open an issue or PR! This started as a personal project, but I'm happy to collaborate.

License

MIT - Use it however you want!

Why I Built This

I was getting frustrated with the limited Supabase integrations available for Claude, especially for self-hosted instances. Wanted something comprehensive that could handle everything I throw at it. Hope it helps you too!