Supabase Self-Hosted MCP

A comprehensive Model Context Protocol (MCP) server for Supabase. Works with self-hosted Supabase (Coolify, Docker) and Supabase Cloud.

53 tools across 10 categories for complete database management through Claude Code, Cursor, or any MCP-compatible client.

Turkish Documentation / Türkçe Dokümantasyon

Features

Database Introspection (8 tools)

• List tables with size and row counts
• Column details with types, constraints, defaults
• Indexes and their usage statistics
• Foreign key relationships
• Views, functions, triggers
• Enum types

Security (6 tools)

• List RLS policies
• Check RLS status on tables
• Create/drop RLS policies
• Enable/disable RLS
• Analyze table permissions

Query Operations (8 tools)

• SELECT with filters, ordering, pagination
• INSERT (single/batch)
• UPDATE with required filters
• DELETE with required filters
• Raw SQL execution
• RPC function calls
• Multi-query transactions
• Query execution plans (EXPLAIN)

Schema Management (4 tools)

• CREATE TABLE with constraints
• ALTER TABLE (add/drop/modify columns)
• DROP TABLE
• CREATE INDEX

Storage (8 tools)

• List/create buckets
• List/delete files
• Get public URLs
• Generate signed URLs with transformations
• Move/copy files

Auth (6 tools)

• List users with pagination
• Get user details
• Create/update/delete users
• Send email invitations

Realtime (4 tools)

• List PostgreSQL publications
• List publication tables
• Enable/disable realtime for tables

Edge Functions (1 tool)

• Invoke edge functions

Optimization (6 tools)

• Normalization analysis
• Unused index detection
• Index recommendations
• Duplicate data detection
• Table bloat analysis
• Slow query analysis

Health (2 tools)

• Connection statistics
• Slow query monitoring

Installation

Option 1: npm (Recommended)

npx supabase-self-hosted-mcp

Or install globally:

npm install -g supabase-self-hosted-mcp
supabase-self-hosted-mcp

Option 2: Clone Repository

git clone https://github.com/abdullah017/supabase-self-hosted-toolkit.git
cd supabase-self-hosted-toolkit
npm install
npm run build

Configuration

Environment Variables

# Required
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your-service-role-key

# Optional (enables advanced features)
POSTGRES_URL=postgresql://postgres:password@host:5432/postgres
# or
DATABASE_URL=postgresql://postgres:password@host:5432/postgres

# Optional settings
LOG_LEVEL=info              # debug, info, warn, error
MAX_POOL_SIZE=10           # PostgreSQL connection pool size
CONNECTION_TIMEOUT=30000   # Connection timeout in ms

Getting Credentials

Supabase Cloud

1. Go to Supabase Dashboard
2. Select your project
3. Settings → API
4. Copy Project URL and service_role key

Self-Hosted (Coolify/Docker)

1. SUPABASE_URL: Your Supabase URL (e.g., https://supabase.yourdomain.com)
2. SUPABASE_SERVICE_KEY: Found in environment variables as SERVICE_ROLE_KEY
3. POSTGRES_URL: postgresql://postgres:YOUR_PASSWORD@db.yourdomain.com:5432/postgres

Claude Code Integration

Global Configuration

Edit ~/.claude/claude_code_config.json:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "supabase-self-hosted-mcp"],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_KEY": "your-service-role-key",
        "POSTGRES_URL": "postgresql://postgres:password@host:5432/postgres"
      }
    }
  }
}

Project-Specific Configuration

Create .claude/mcp.json in your project root:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "supabase-self-hosted-mcp"],
      "env": {
        "SUPABASE_URL": "${SUPABASE_URL}",
        "SUPABASE_SERVICE_KEY": "${SUPABASE_SERVICE_KEY}",
        "POSTGRES_URL": "${POSTGRES_URL}"
      }
    }
  }
}

Then add values to your .env file.

Cursor Integration

Add to Cursor settings (Settings → MCP):

{
  "supabase": {
    "command": "npx",
    "args": ["-y", "supabase-mcp"],
    "env": {
      "SUPABASE_URL": "your-url",
      "SUPABASE_SERVICE_KEY": "your-key"
    }
  }
}

Usage Examples

Database Structure

"List all tables in the database"
"Show the structure of the users table"
"What are the foreign key relationships?"
"Which tables have RLS enabled?"

Querying Data

"Get the last 10 records from users"
"Insert a new product into products table"
"Update user status where id = 123"
"Run SELECT * FROM orders WHERE status = 'pending'"

Optimization

"Analyze normalization issues in my database"
"Find unused indexes"
"Suggest indexes for the orders table"
"Show slow queries"
"Check for table bloat"

Security

"Create an RLS policy for users table that allows users to see only their own data"
"Analyze permissions on all tables"
"Enable RLS on the posts table"

Schema Management

"Create a new table called categories"
"Add a phone column to the users table"
"Create an index on orders.user_id"

Storage

"List all storage buckets"
"Get a signed URL for file.pdf in documents bucket"
"Move image.png to archive folder"

Auth

"List all users"
"Create a new user with email test@example.com"
"Invite user@example.com to the project"

Realtime

"Enable realtime for the messages table"
"List tables that have realtime enabled"

Tool Reference

Category	Tools
Introspection	list_tables, get_table_columns, get_indexes, get_foreign_keys, get_views, get_functions, get_triggers, get_enums
Security	list_rls_policies, check_rls_status, create_rls_policy, drop_rls_policy, toggle_rls, analyze_permissions
Query	query, insert, update, delete, raw_sql, rpc, transaction, explain_query
Schema	create_table, alter_table, drop_table, create_index
Storage	list_buckets, create_bucket, list_files, delete_file, get_public_url, get_signed_url, move_file, copy_file
Auth	list_users, get_user, delete_user, create_user, update_user, invite_user
Realtime	list_publications, list_publication_tables, enable_realtime, disable_realtime
Edge Functions	invoke_edge_function
Optimization	analyze_normalization, get_unused_indexes, suggest_indexes, find_duplicate_data, get_table_bloat, get_slow_queries
Health	get_connection_stats, get_slow_queries

Security Notes

1. Service Role Key: This key has admin privileges. Keep it secure and never expose it in client-side code.
2. Raw SQL: Use parameterized queries when possible to prevent SQL injection.
3. RLS: Always enable RLS on tables that contain user data.
4. Network: The MCP server should only run locally or in a secure environment.

PostgreSQL Features

Some features require a direct PostgreSQL connection (via POSTGRES_URL):

• Raw SQL execution
• Transaction support
• Query execution plans
• Normalization analysis
• Slow query analysis
• Table bloat detection
• Realtime management

Troubleshooting

"POSTGRES_URL is required"

Some advanced features require a direct PostgreSQL connection. Add POSTGRES_URL or DATABASE_URL to your environment.

Connection refused

• Ensure PostgreSQL is accessible from your network
• Check firewall rules
• Verify the connection string format

Permission denied

• Verify the service role key is correct
• Ensure the PostgreSQL user has sufficient privileges

MCP not loading in Claude Code

• Check the JSON syntax in config files
• Verify the path to the MCP server
• Check Claude Code logs: ~/.claude/logs/

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

MIT License - see LICENSE for details.

Related Projects

• Supabase
• Model Context Protocol
• Claude Code