selfhosted supabase mcp

Local 2025-09-01 01:07:16 0
Developer Tools @HenkDz/selfhosted-supabase-mcp

A protocol server that enables interaction with self-hosted Supabase instances directly from development environments, allowing database introspection, management of migrations, auth users, and storage through MCP clients like IDE extensions.

x000D License: MITx000D x000D

Overview_x000D_

x000D This project provides a Model Context Protocol (MCP) server designed specifically for interacting with self-hosted Supabase instances. It bridges the gap between MCP clients (like IDE extensions) and your local or privately hosted Supabase projects, enabling database introspection, management, and interaction directly from your development environment.x000D x000D This server was built from scratch, drawing lessons from adapting the official Supabase cloud MCP server, to provide a minimal, focused implementation tailored for the self-hosted use case.x000D x000D

Purpose_x000D_

x000D The primary goal of this server is to enable developers using self-hosted Supabase installations to leverage MCP-based tools for tasks such as:x000D x000D * Querying database schemas and data.x000D * Managing database migrations.x000D * Inspecting database statistics and connections.x000D * Managing authentication users.x000D * Interacting with Supabase Storage.x000D * Generating type definitions.x000D x000D It avoids the complexities of the official cloud server related to multi-project management and cloud-specific APIs, offering a streamlined experience for single-project, self-hosted environments.x000D x000D

Features (Implemented Tools)x000D

x000D The server exposes the following tools to MCP clients:x000D x000D * Schema & Migrationsx000D * list_tables: Lists tables in the database schemas.x000D * list_extensions: Lists installed PostgreSQL extensions.x000D * list_migrations: Lists applied Supabase migrations.x000D * apply_migration: Applies a SQL migration script.x000D * Database Operations & Statsx000D * execute_sql: Executes an arbitrary SQL query (via RPC or direct connection).x000D * get_database_connections: Shows active database connections (pg_stat_activity).x000D * get_database_stats: Retrieves database statistics (pg_stat_*).x000D * Project Configuration & Keysx000D * get_project_url: Returns the configured Supabase URL.x000D * get_anon_key: Returns the configured Supabase anon key.x000D * get_service_key: Returns the configured Supabase service role key (if provided).x000D * verify_jwt_secret: Checks if the JWT secret is configured and returns a preview.x000D * Development & Extension Toolsx000D * generate_typescript_types: Generates TypeScript types from the database schema.x000D * rebuild_hooks: Attempts to restart the pg_net worker (if used).x000D * Auth User Managementx000D * list_auth_users: Lists users from auth.users.x000D * get_auth_user: Retrieves details for a specific user.x000D * create_auth_user: Creates a new user (Requires direct DB access, insecure password handling).x000D * delete_auth_user: Deletes a user (Requires direct DB access).x000D * update_auth_user: Updates user details (Requires direct DB access, insecure password handling).x000D * Storage Insightsx000D * list_storage_buckets: Lists all storage buckets.x000D * list_storage_objects: Lists objects within a specific bucket.x000D * Realtime Inspectionx000D * list_realtime_publications: Lists PostgreSQL publications (often supabase_realtime).x000D x000D (Note: get_logs was initially planned but skipped due to implementation complexities in a self-hosted environment).x000D x000D

Setup and Installation_x000D_

x000D

Prerequisites_x000D_

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

Steps_x000D_

x000D 1. Clone the repository:x000D bash_x000D_ git clone <repository-url>_x000D_ cd self-hosted-supabase-mcp_x000D_x000D 2. Install dependencies:x000D bash_x000D_ npm install_x000D_x000D 3. Build the project:x000D bash_x000D_ npm run build_x000D_x000D This compiles the TypeScript code to JavaScript in the dist directory.x000D x000D

Configuration_x000D_

x000D The server requires configuration details for your Supabase instance. These can be provided via command-line arguments or environment variables. CLI arguments take precedence.x000D x000D Required:x000D x000D * --url <url> or SUPABASE_URL=<url>: The main HTTP URL of your Supabase project (e.g., http://localhost:8000).x000D * --anon-key <key> or SUPABASE_ANON_KEY=<key>: Your Supabase project s anonymous key.x000D x000D Optional (but Recommended/Required for certain tools):x000D x000D * --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.x000D * --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.).x000D * --jwt-secret <secret> or SUPABASE_AUTH_JWT_SECRET=<secret>: Your Supabase project s JWT secret. Needed for tools like verify_jwt_secret.x000D * --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"]}.x000D x000D

Important Notes:x000D

x000D * 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.x000D * 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.x000D x000D

Usage_x000D_

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

Using CLI arguments (example)x000D

node dist/index.js --url http://localhost:8000 --anon-key --db-url postgresql://postgres:password@localhost:5432/postgres [--service-key ]x000D x000D

Example with tool whitelisting via config file_x000D_

node dist/index.js --url http://localhost:8000 --anon-key --tools-config ./mcp-tools.json_x000D_ x000D

Or configure using environment variables and run:x000D

export SUPABASE_URL=http://localhost:8000_x000D_

export SUPABASE_ANON_KEY=x000D

export DATABASE_URL=postgresql://postgres:password@localhost:5432/postgres_x000D_

export SUPABASE_SERVICE_ROLE_KEY=x000D

The --tools-config option MUST be passed as a CLI argument if used_x000D_

node dist/index.js_x000D_ x000D

Using npm start script (if configured in package.json to pass args/read env)x000D

npm start -- --url ... --anon-key ...x000D ```x000D x000D 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.x000D x000D

Client Configuration Examples_x000D_

x000D Below are examples of how to configure popular MCP clients to use this self-hosted server. x000D x000D Important: x000D * Replace placeholders like <your-supabase-url>, <your-anon-key>, <your-db-url>, <path-to-dist/index.js> etc., with your actual values.x000D * Ensure the path to the compiled server file (dist/index.js) is correct for your system.x000D * 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.x000D x000D

Cursor_x000D_

x000D 1. Create or open the file .cursor/mcp.json in your project root.x000D 2. Add the following configuration:x000D x000D json_x000D_ {_x000D_ "mcpServers": {_x000D_ "selfhosted-supabase": { _x000D_ "command": "node",_x000D_ "args": [_x000D_ "<path-to-dist/index.js>", // e.g., "F:/Projects/mcp-servers/self-hosted-supabase-mcp/dist/index.js"_x000D_ "--url",_x000D_ "<your-supabase-url>", // e.g., "http://localhost:8000"_x000D_ "--anon-key",_x000D_ "<your-anon-key>",_x000D_ // Optional - Add these if needed by the tools you use_x000D_ "--service-key",_x000D_ "<your-service-key>",_x000D_ "--db-url",_x000D_ "<your-db-url>", // e.g., "postgresql://postgres:password@host:port/postgres"_x000D_ "--jwt-secret",_x000D_ "<your-jwt-secret>",_x000D_ // Optional - Whitelist specific tools_x000D_ "--tools-config",_x000D_ "<path-to-your-mcp-tools.json>" // e.g., "./mcp-tools.json"_x000D_ ]_x000D_ }_x000D_ }_x000D_ }_x000D_x000D x000D

Visual Studio Code (Copilot)x000D

x000D VS Code Copilot allows using environment variables populated via prompted inputs, which is more secure for keys.x000D x000D 1. Create or open the file .vscode/mcp.json in your project root.x000D 2. Add the following configuration:x000D x000D json_x000D_ {_x000D_ "inputs": [_x000D_ { "type": "promptString", "id": "sh-supabase-url", "description": "Self-Hosted Supabase URL", "default": "http://localhost:8000" },_x000D_ { "type": "promptString", "id": "sh-supabase-anon-key", "description": "Self-Hosted Supabase Anon Key", "password": true },_x000D_ { "type": "promptString", "id": "sh-supabase-service-key", "description": "Self-Hosted Supabase Service Key (Optional)", "password": true, "required": false },_x000D_ { "type": "promptString", "id": "sh-supabase-db-url", "description": "Self-Hosted Supabase DB URL (Optional)", "password": true, "required": false },_x000D_ { "type": "promptString", "id": "sh-supabase-jwt-secret", "description": "Self-Hosted Supabase JWT Secret (Optional)", "password": true, "required": false },_x000D_ { "type": "promptString", "id": "sh-supabase-server-path", "description": "Path to self-hosted-supabase-mcp/dist/index.js" },_x000D_ { "type": "promptString", "id": "sh-supabase-tools-config", "description": "Path to tools config JSON (Optional, e.g., ./mcp-tools.json)", "required": false }_x000D_ ],_x000D_ "servers": {_x000D_ "selfhosted-supabase": {_x000D_ "command": "node",_x000D_ // Arguments are passed via environment variables set below OR direct args for non-env options_x000D_ "args": [_x000D_ "${input:sh-supabase-server-path}",_x000D_ // Use direct args for options not easily map-able to standard env vars like tools-config_x000D_ // Check if tools-config input is provided before adding the argument_x000D_ ["--tools-config", "${input:sh-supabase-tools-config}"] _x000D_ // Alternatively, pass all as args if simpler:_x000D_ // "--url", "${input:sh-supabase-url}",_x000D_ // "--anon-key", "${input:sh-supabase-anon-key}",_x000D_ // ... etc ... _x000D_ ],_x000D_ "env": {_x000D_ "SUPABASE_URL": "${input:sh-supabase-url}",_x000D_ "SUPABASE_ANON_KEY": "${input:sh-supabase-anon-key}",_x000D_ "SUPABASE_SERVICE_ROLE_KEY": "${input:sh-supabase-service-key}",_x000D_ "DATABASE_URL": "${input:sh-supabase-db-url}",_x000D_ "SUPABASE_AUTH_JWT_SECRET": "${input:sh-supabase-jwt-secret}"_x000D_ // The server reads these environment variables as fallbacks if CLI args are missing_x000D_ }_x000D_ }_x000D_ }_x000D_ }_x000D_x000D 3. When you use Copilot Chat in Agent mode (@workspace), it should detect the server. You will be prompted to enter the details (URL, keys, path) when the server is first invoked.x000D x000D

Other Clients (Windsurf, Cline, Claude)x000D

x000D Adapt the configuration structure shown for Cursor or the official Supabase documentation, replacing the command and args with the node command and the arguments for this server, similar to the Cursor example:x000D x000D json_x000D_ {_x000D_ "mcpServers": {_x000D_ "selfhosted-supabase": { _x000D_ "command": "node",_x000D_ "args": [_x000D_ "<path-to-dist/index.js>", _x000D_ "--url", "<your-supabase-url>", _x000D_ "--anon-key", "<your-anon-key>", _x000D_ // Optional args..._x000D_ "--service-key", "<your-service-key>", _x000D_ "--db-url", "<your-db-url>", _x000D_ "--jwt-secret", "<your-jwt-secret>",_x000D_ // Optional tools config_x000D_ "--tools-config", "<path-to-your-mcp-tools.json>"_x000D_ ]_x000D_ }_x000D_ }_x000D_ }_x000D_x000D Consult the specific documentation for each client on where to place the mcp.json or equivalent configuration file.x000D x000D

Development_x000D_

x000D * Language: TypeScript_x000D_ * Build: tsc (TypeScript Compiler)x000D * Dependencies: Managed via npm (package.json)x000D * Core Libraries: @supabase/supabase-js, pg (node-postgres), zod (validation), commander (CLI args), @modelcontextprotocol/sdk (MCP server framework).x000D x000D

License_x000D_

x000D This project is licensed under the MIT License. See the LICENSE file for details.