Self-Hosted Supabase MCP Server

MCP (Model Context Protocol) server for self-hosted Supabase instances. Allows AI assistants like Claude to interact with your self-hosted Supabase database.

Originally developed by HenkDz, now maintained by lemontreen.

Features

This server exposes a rich set of tools for interacting with your self-hosted Supabase instance:

• Database Schema
  • list_tables: Lists all tables in the public schema.
  • list_extensions: Lists installed PostgreSQL extensions.
  • get_database_connections: Retrieves current database connection information.
  • get_database_stats: Gets database statistics (e.g., table sizes).
• Migrations & SQL
  • list_migrations: Lists applied migrations from the supabase_migrations schema.
  • apply_migration: Applies a new SQL migration (Requires direct DB access).
  • execute_sql: Executes arbitrary SQL (Requires helper function in DB or direct DB access).
  • generate_typescript_types: Generates TypeScript types from the database schema.
• Project Configuration
  • get_project_url: Returns the configured Supabase project 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: Verifies the provided JWT secret against the database (Requires direct DB access).
• Infrastructure
  • rebuild_hooks: Attempts to restart the pg_net worker (if used).
• Auth User Management
  • list_auth_users: Lists users from auth.users.
  • get_auth_user: Retrieves details for a specific user.
  • create_auth_user: Creates a new user (Requires direct DB access, insecure password handling).
  • delete_auth_user: Deletes a user (Requires direct DB access).
  • update_auth_user: Updates user details (Requires direct DB access, insecure password handling).
• Storage Insights
  • list_storage_buckets: Lists all storage buckets.
  • list_storage_objects: Lists objects within a specific bucket.
• Realtime Inspection
  • list_realtime_publications: Lists PostgreSQL publications (often supabase_realtime).

(Note: get_logs was initially planned but skipped due to implementation complexities in a self-hosted environment).

Setup and Installation

Method 1: Using npx (Recommended)

The easiest way to use this server is via npx, which requires no installation:

npx @lemontreen/rds-supabase-mcp-server --url http://localhost:8000 --anon-key YOUR_ANON_KEY

Method 2: Installing via Smithery

To install Self-Hosted Supabase MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @HenkDz/selfhosted-supabase-mcp --client claude

Method 3: Global Installation

Install the package globally:

npm install -g @lemontreen/rds-supabase-mcp-server
supabase-mcp --url http://localhost:8000 --anon-key YOUR_ANON_KEY

Method 4: Local Installation and Build

If you want to build from source:

Prerequisites

• Node.js (Version 18.x or later recommended)
• npm (usually included with Node.js)
• Access to your self-hosted Supabase instance (URL, keys, potentially direct DB connection string).

Steps

1. Clone the repository:

   git clone <repository-url>
   cd selfhosted-supabase-mcp

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

   This compiles the TypeScript code to JavaScript in the dist directory.

Configuration

The server requires configuration details for your Supabase instance. These can be provided via command-line arguments or environment variables. CLI arguments take precedence.

Required:

• --url <url> or SUPABASE_URL=<url>: The main HTTP URL of your Supabase project (e.g., http://localhost:8000).
• --anon-key <key> or SUPABASE_ANON_KEY=<key>: Your Supabase project's anonymous key.

Optional (but Recommended/Required for certain tools):

• --service-key <key> or SUPABASE_SERVICE_ROLE_KEY=<key>: Your Supabase project's service role key. Needed for operations requiring elevated privileges, like attempting to automatically create the execute_sql helper function if it doesn't exist.
• --db-url <url> or DATABASE_URL=<url>: The direct PostgreSQL connection string for your Supabase database (e.g., postgresql://postgres:password@localhost:5432/postgres). Required for tools needing direct database access or transactions (apply_migration, Auth tools, Storage tools, querying pg_catalog, etc.).
• --jwt-secret <secret> or SUPABASE_AUTH_JWT_SECRET=<secret>: Your Supabase project's JWT secret. Needed for tools like verify_jwt_secret.
• --tools-config <path>: Path to a JSON file specifying which tools to enable (whitelist). If omitted, all tools defined in the server are enabled. The file should have the format {"enabledTools": ["tool_name_1", "tool_name_2"]}.

Important Notes:

• execute_sql Helper Function: Many tools rely on a public.execute_sql function within your Supabase database for secure and efficient SQL execution via RPC. The server attempts to check for this function on startup. If it's missing and a service-key (or SUPABASE_SERVICE_ROLE_KEY) and db-url (or DATABASE_URL) are provided, it will attempt to create the function and grant necessary permissions. If creation fails or keys aren't provided, tools relying solely on RPC may fail.
• Direct Database Access: Tools interacting directly with privileged schemas (auth, storage) or system catalogs (pg_catalog) generally require the DATABASE_URL to be configured for a direct pg connection.

Usage

Run the server using Node.js, providing the necessary configuration:

# Using npx (no installation required)
npx @lemontreen/rds-supabase-mcp-server --url http://localhost:8000 --anon-key <your-anon-key> --db-url postgresql://postgres:password@localhost:5432/postgres [--service-key <your-service-key>]

# Using CLI arguments (example)
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>]

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

# Or configure using 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>
# The --tools-config option MUST be passed as a CLI argument if used
node dist/index.js

# Using npm start script (if configured in package.json to pass args/read env)
npm start -- --url ... --anon-key ...

The server communicates via standard input/output (stdio) and is designed to be invoked by an MCP client application (e.g., an IDE extension like Cursor). The client will connect to the server's stdio stream to list and call the available tools.

Client Configuration Examples

Below are examples of how to configure popular MCP clients to use this self-hosted server.

Important:

• Replace placeholders like <your-supabase-url>, <your-anon-key>, <your-db-url>, <path-to-dist/index.js> etc., with your actual values.
• Ensure the path to the compiled server file (dist/index.js) is correct for your system.
• Be cautious about storing sensitive keys directly in configuration files, especially if committed to version control. Consider using environment variables or more secure methods where supported by the client.

Cursor

1. Create or open the file .cursor/mcp.json in your project root.

2. Add the following configuration:

   {
     "mcpServers": {
       "selfhosted-supabase": { 
         "command": "npx",
         "args": [
           "@lemontreen/rds-supabase-mcp-server",
           "--url",
           "<your-supabase-url>", // e.g., "http://localhost:8000"
           "--anon-key",
           "<your-anon-key>",
           // Optional - Add these if needed by the tools you use
           "--service-key",
           "<your-service-key>",
           "--db-url",
           "<your-db-url>", // e.g., "postgresql://postgres:password@host:port/postgres"
           "--jwt-secret",
           "<your-jwt-secret>",
           // Optional - Whitelist specific tools
           "--tools-config",
           "<path-to-tools-config.json>"
         ]
       }
     }
   }

Claude for Desktop

For Claude Desktop, you can add the following to your configuration:

1. Open Claude Desktop Settings

2. Go to "Developer" and enable "Custom MCP Servers"

3. Add a new server with the following configuration:

   {
     "name": "Self-Hosted Supabase",
     "command": "npx",
     "args": [
       "@lemontreen/rds-supabase-mcp-server",
       "--url",
       "http://localhost:8000",
       "--anon-key",
       "YOUR_ANON_KEY_HERE"
     ]
   }

Development

To develop and contribute to this project:

1. Clone the repository
2. Run npm install
3. Make your changes
4. Run npm run build to compile
5. Test with node dist/index.js or directly with an MCP client

License

This project is licensed under the MIT License - see the LICENSE file for details.

Originally developed by HenkDz, now maintained by lemontreen.