Self-Hosted Supabase MCP Server

How to use

Connect an MCP client to the server using a stdio-based configuration. You start the server locally and the client communicates over the standard input/output stream. The server exposes tools to inspect schemas, run migrations, manage auth users, access storage insights, generate type definitions, and perform direct SQL operations when you provide a direct database URL.

How to install

Prerequisites: install Node.js (version 18 or newer recommended) and npm. You also need access to your self-hosted Supabase instance (URL, anon key, and optionally a direct database connection string).

Step 1: Install dependencies and build the project. Run these commands in your project directory:
```bash
npm install
```
```bash
npm run build
```
The build compiles TypeScript to JavaScript in the dist directory.

Usage basics

Start the server using Node.js by pointing it at the compiled entry and passing your Supabase configuration. A typical start command looks like this:

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>]
```
Then you can optionally whitelist tools with a tools configuration file: `--tools-config ./mcp-tools.json`.

Run as part of a local MCP workflow

You can also run the server via environment variables, letting CLI arguments be supplied as fallbacks. Example environment setup (then run the server with no extra args):

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
```
If you use a tools whitelist, provide it with `--tools-config`.

Configuration

Configure the server with the essential details of your Supabase instance. You must provide the main URL and anon key. You can optionally provide the service key for elevated operations, a direct database URL for privileged tools, and a JWT secret for verification tasks.

--url <supabase-url>
--anon-key <anon-key>
--service-key <service-key>
--db-url <database-url>
--jwt-secret <jwt-secret>
--tools-config <path-to-tools.json>
```
CLI arguments take precedence over environment variables.

Security and keys

Keep your keys secure. The server uses the provided database URL for privileged operations and can generate or verify credentials as needed. If you rely on RPC-style SQL execution, ensure the necessary SQL helper is available in your database and properly permissioned.

Tools and capabilities

The server exposes a set of MCP tools organized by capability. You can perform schema discovery, migrations, SQL execution, database statistics, auth user management, storage inspection, and real-time publication inspection. A separate configuration file can whitelist specific tools if you want to limit what is exposed.

Client configuration examples

To connect from an MCP client, reference the stdio-based command including the path to the built server and the required arguments. For example, configure your client to run the Node host and point to the compiled entry, then supply your Supabase URL and keys.

Development

Language: TypeScript
Build: tsc (TypeScript Compiler)
Dependencies: npm-managed
Core libraries: @supabase/supabase-js, pg, zod, commander, @modelcontextprotocol/sdk

Notes

This server is designed for self-hosted Supabase setups and focuses on a streamlined, single-project workflow. It avoids cloud-specific multi-project features and provides practical tools for local development and maintenance.

list_tables

List tables in database schemas.

list_extensions

List installed PostgreSQL extensions.

list_migrations

List applied Supabase migrations.

apply_migration

Apply a SQL migration script.

execute_sql

Execute an arbitrary SQL query via RPC or direct connection.

get_database_connections

Show active database connections.

get_database_stats

Retrieve database statistics.

get_project_url

Return the configured Supabase URL.

get_anon_key

Return the configured anon key.

get_service_key

Return the service role key if provided.

verify_jwt_secret

Check if JWT secret is configured and return a preview.

generate_typescript_types

Generate TypeScript types from the database schema.

rebuild_hooks

Restart the pg_net worker if used.

list_auth_users

List users from auth.users.

get_auth_user

Retrieve details for a specific auth user.

create_auth_user

Create a new auth user (requires direct DB access).

delete_auth_user

Delete an auth user (requires direct DB access).

update_auth_user

Update auth user details (requires direct DB access).

list_storage_buckets

List all storage buckets.

list_storage_objects

List objects within a storage bucket.

list_realtime_publications

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