Self-Hosted Supabase

You can run a self-hosted MCP server that connects to your private Supabase instance to query schemas, manage migrations, inspect auth users, store data, and generate type definitions, all through MCP-enabled clients. This server is designed for single-project, self-hosted setups and streamlines integration with your development tools and IDE extensions.

How to use

Use an MCP client to connect to the self-hosted Supabase MCP server and call the available tools to explore your database, manage migrations, inspect connections, and generate types. You will typically connect using a stdio-based server (local process) or an HTTP-based remote server, then issue tool calls through the MCP client to perform tasks such as listing tables, applying migrations, executing SQL, and generating TypeScript types.

How to install

# Prerequisites are required
- Node.js (Version 18.x or later)
- npm
- Access to your self-hosted Supabase instance (URL, anon key, and optionally a direct DB connection string)

# Install the package and build
git clone <repository-url>
cd selfhosted-supabase-mcp
npm install
npm run build

# Run the server (example using CLI arguments)
node dist/index.js --url http://localhost:8000 --anon-key <your-anon-key> --db-url postgresql://postgres:password@localhost:5432/postgres [--service-key <your-service-key>]

# Alternative start with tool whitelisting via config
node dist/index.js --url http://localhost:8000 --anon-key <your-anon-key> --tools-config ./mcp-tools.json

# Or use environment variables and run
export SUPABASE_URL=http://localhost:8000
export SUPABASE_ANON_KEY=<your-anon-key>
export DATABASE_URL=postgresql://postgres:password@localhost:5432/postgres
export SUPABASE_SERVICE_ROLE_KEY=<your-service-key>
node dist/index.js

Configuration and security notes

Configure the server with your Supabase instance details either through command-line arguments or environment variables. The required pieces are the Supabase URL and anon key. If you plan to perform privileged operations or automate migrations, providing a service role key and a direct database URL improves capability and reliability. Enable or disable tools with a tools config file to limit what is exposed to MCP clients.

Server connection options

# HTTP/remote server (preferred for multi-client setups)
{
  "type": "http",
  "name": "selfhosted_supabase",
  "url": "https://mcp.example.com/mcp",
  "args": []
}

# Stdio/local server (recommended for IDE integrations)
{
  "type": "stdio",
  "name": "selfhosted_supabase",
  "command": "node",
  "args": [
    "dist/index.js",
    "--url", "<your-supabase-url>",
    "--anon-key", "<your-anon-key>",
    "--service-key", "<your-service-key>",
    "--db-url", "<your-db-url>",
    "--jwt-secret", "<your-jwt-secret>",
    "--tools-config", "<path-to-your-mcp-tools.json>"
  ],
  "env": {
    "SUPABASE_URL": "<your-supabase-url>",
    "SUPABASE_ANON_KEY": "<your-anon-key>",
    "SUPABASE_SERVICE_ROLE_KEY": "<your-service-key>",
    "DATABASE_URL": "<your-db-url>",
    "SUPABASE_AUTH_JWT_SECRET": "<your-jwt-secret>"
  }
}

Tools and capabilities you can call

The server exposes a broad set of tools to interact with your Supabase setup, covering schema inspection, migrations, database operations, project configuration, auth user management, storage insights, and realtime inspection.

Usage with MCP clients

Connect your MCP client to the local stdio server or to the remote HTTP server and select the tools you need. You will call each tool by name, supply the required parameters, and receive results back through the MCP channel.

Development

The server is implemented in TypeScript and built with the TypeScript compiler. It relies on common libraries for Supabase interaction, PostgreSQL access, validation, CLI argument parsing, and the MCP server framework.

Available tools

list_tables

Lists tables in the database schemas.

list_extensions

Lists installed PostgreSQL extensions.

list_migrations

Lists applied Supabase migrations.

apply_migration

Applies a SQL migration script.

execute_sql

Executes an arbitrary SQL query (via RPC or direct connection).

get_database_connections

Shows active database connections via pg_stat_activity.

get_database_stats

Retrieves database statistics from pg_stat_* views.

get_project_url

Returns the configured Supabase URL.

get_anon_key

Returns the configured Supabase anon key.

get_service_key

Returns the configured Supabase service role key (if provided).

verify_jwt_secret

Checks if the JWT secret is configured and returns a preview.

generate_typescript_types

Generates TypeScript types from the database schema.

rebuild_hooks

Attempts to restart the pg_net worker (if used).

list_auth_users

Lists users from auth.users.

get_auth_user

Retrieves details for a specific user.

create_auth_user

Creates a new auth user (Requires direct DB access).

delete_auth_user

Deletes an auth user (Requires direct DB access).

update_auth_user

Updates user details (Requires direct DB access).

list_storage_buckets

Lists all storage buckets.

list_storage_objects

Lists objects within a storage bucket.

list_realtime_publications

Lists PostgreSQL publications (e.g., supabase_realtime).