Self-Hosted Supabase MCP Server

Interact with self-hosted Supabase instances for database management and introspection.

This project provides aModel Context Protocol (MCP)server designed specifically for interacting withself-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.

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

git clone <repository-url> cd self-hosted-supabase-mcp

- execute_sqlHelper Function:Many tools rely on apublic.execute_sqlfunction 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 missingandaservice-key(orSUPABASE_SERVICE_ROLE_KEY)and*db-url(orDATABASE_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 theDATABASE_URLto be configured for a directpgconnection.

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

# 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.

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

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

Create or open the file.cursor/mcp.jsonin your project root.

{ "mcpServers": { "selfhosted-supabase": { "command": "node", "args": [ "<path-to-dist/index.js>", // e.g., "F:/Projects/mcp-servers/self-hosted-supabase-mcp/dist/index.js" "--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-your-mcp-tools.json>" // e.g., "./mcp-tools.json" ] } } }

VS Code Copilot allows using environment variables populated via prompted inputs, which is more secure for keys.
-

Create or open the file.vscode/mcp.jsonin your project root.

{ "inputs": [ { "type": "promptString", "id": "sh-supabase-url", "description": "Self-Hosted Supabase URL", "default": "http://localhost:8000" }, { "type": "promptString", "id": "sh-supabase-anon-key", "description": "Self-Hosted Supabase Anon Key", "password": true }, { "type": "promptString", "id": "sh-supabase-service-key", "description": "Self-Hosted Supabase Service Key (Optional)", "password": true, "required": false }, { "type": "promptString", "id": "sh-supabase-db-url", "description": "Self-Hosted Supabase DB URL (Optional)", "password": true, "required": false }, { "type": "promptString", "id": "sh-supabase-jwt-secret", "description": "Self-Hosted Supabase JWT Secret (Optional)", "password": true, "required": false }, { "type": "promptString", "id": "sh-supabase-server-path", "description": "Path to self-hosted-supabase-mcp/dist/index.js" }, { "type": "promptString", "id": "sh-supabase-tools-config", "description": "Path to tools config JSON (Optional, e.g., ./mcp-tools.json)", "required": false } ], "servers": { "selfhosted-supabase": { "command": "node", // Arguments are passed via environment variables set below OR direct args for non-env options "args": [ "${input:sh-supabase-server-path}", // Use direct args for options not easily map-able to standard env vars like tools-config // Check if tools-config input is provided before adding the argument ["--tools-config", "${input:sh-supabase-tools-config}"] // Alternatively, pass all as args if simpler: // "--url", "${input:sh-supabase-url}", // "--anon-key", "${input:sh-supabase-anon-key}", // ... etc ... ], "env": { "SUPABASE_URL": "${input:sh-supabase-url}", "SUPABASE_ANON_KEY": "${input:sh-supabase-anon-key}", "SUPABASE_SERVICE_ROLE_KEY": "${input:sh-supabase-service-key}", "DATABASE_URL": "${input:sh-supabase-db-url}", "SUPABASE_AUTH_JWT_SECRET": "${input:sh-supabase-jwt-secret}" // The server reads these environment variables as fallbacks if CLI args are missing } } } }

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.

Adapt the configuration structure shown for Cursor or the official Supabase documentation, replacing thecommandandargswith thenodecommand and the arguments for this server, similar to the Cursor example:

{ "mcpServers": { "selfhosted-supabase": { "command": "node", "args": [ "<path-to-dist/index.js>", "--url", "<your-supabase-url>", "--anon-key", "<your-anon-key>", // Optional args... "--service-key", "<your-service-key>", "--db-url", "<your-db-url>", "--jwt-secret", "<your-jwt-secret>", // Optional tools config "--tools-config", "<path-to-your-mcp-tools.json>" ] } } }

Consult the specific documentation for each client on where to place themcp.jsonor equivalent configuration file.

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

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

Official Supabase MCP server for managing Supabase projects, databases, auth, storage, edge functions, and SQL workflows from AI agents.

Securely access BigQuery datasets with intelligent caching, schema tracking, and query analytics via Supabase integration.

Interact with self-hosted Supabase instances for database introspection, management, and interaction.

Interact with Supabase databases, query tables, and generate TypeScript types.

A server for querying and managing data in a Supabase database.

Provides access to supOS open APIs for querying topic structures, real-time and historical data, and executing SQL queries.

Official MCP server for dbt (data build tool) providing integration with dbt Core/Cloud CLI, project metadata discovery, model information, and semantic layer querying capabilities.

Open source MCP server specializing in easy, fast, and secure tools for Databases.

Query and analyze data with MotherDuck and local DuckDB