Integrations
Provides tools for direct PostgreSQL database operations, including executing SQL queries, viewing database connections and statistics, listing extensions, and querying system catalogs.
Enables interaction with self-hosted Supabase instances, providing tools for database introspection, SQL query execution, schema management, migrations, auth user management, storage bucket operations, and TypeScript type generation.
Self-Hosted Supabase MCP Server
Overview
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.
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.
Purpose
The primary goal of this server is to enable developers using self-hosted Supabase installations to leverage MCP-based tools for tasks such as:
- Querying database schemas and data.
- Managing database migrations.
- Inspecting database statistics and connections.
- Managing authentication users.
- Interacting with Supabase Storage.
- Generating type definitions.
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.
Features (Implemented Tools)
The server exposes the following tools to MCP clients:
- Schema & Migrations
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.
- Database Operations & Stats
execute_sql
: Executes an arbitrary SQL query (via RPC or direct connection).get_database_connections
: Shows active database connections (pg_stat_activity
).get_database_stats
: Retrieves database statistics (pg_stat_*
).
- Project Configuration & Keys
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.
- Development & Extension Tools
generate_typescript_types
: Generates TypeScript types from the database schema.rebuild_hooks
: Attempts to restart thepg_net
worker (if used).
- Auth User Management
list_auth_users
: Lists users fromauth.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 (oftensupabase_realtime
).
(Note: get_logs
was initially planned but skipped due to implementation complexities in a self-hosted environment).
Setup and Installation
Installing via Smithery
To install Self-Hosted Supabase MCP Server for Claude Desktop automatically via Smithery:
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
- Clone the repository:Copy
- Install dependencies:Copy
- Build the project:This compiles the TypeScript code to JavaScript in theCopy
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>
orSUPABASE_URL=<url>
: The main HTTP URL of your Supabase project (e.g.,http://localhost:8000
).--anon-key <key>
orSUPABASE_ANON_KEY=<key>
: Your Supabase project's anonymous key.
Optional (but Recommended/Required for certain tools):
--service-key <key>
orSUPABASE_SERVICE_ROLE_KEY=<key>
: Your Supabase project's service role key. Needed for operations requiring elevated privileges, like attempting to automatically create theexecute_sql
helper function if it doesn't exist.--db-url <url>
orDATABASE_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, queryingpg_catalog
, etc.).--jwt-secret <secret>
orSUPABASE_AUTH_JWT_SECRET=<secret>
: Your Supabase project's JWT secret. Needed for tools likeverify_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 apublic.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 aservice-key
(orSUPABASE_SERVICE_ROLE_KEY
) anddb-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_URL
to be configured for a directpg
connection.
Usage
Run the server using Node.js, providing the necessary configuration:
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
- Create or open the file
.cursor/mcp.json
in your project root. - Add the following configuration:Copy
Visual Studio Code (Copilot)
VS Code Copilot allows using environment variables populated via prompted inputs, which is more secure for keys.
- Create or open the file
.vscode/mcp.json
in your project root. - Add the following configuration:Copy
- 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.
Other Clients (Windsurf, Cline, Claude)
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:
Consult the specific documentation for each client on where to place the mcp.json
or equivalent configuration file.
Development
- Language: TypeScript
- Build:
tsc
(TypeScript Compiler) - Dependencies: Managed via
npm
(package.json
) - Core Libraries:
@supabase/supabase-js
,pg
(node-postgres),zod
(validation),commander
(CLI args),@modelcontextprotocol/sdk
(MCP server framework).
License
This project is licensed under the MIT License. See the LICENSE file for details.
You must be authenticated.
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
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.
Related MCP Servers
- AsecurityFlicenseAqualityA Model Context Protocol (MCP) server that provides programmatic access to the Supabase Management API. This server allows AI models and other clients to manage Supabase projects and organizations through a standardized interface.Last updated -88427JavaScript
- AsecurityAlicenseAqualityAn MCP server that provides tools for interacting with Supabase databases, storage, and edge functions.Last updated -1441JavaScriptMIT License
- -security-license-qualityAn MCP server utilizing Supabase to provide memory and knowledge graph storage, enabling multiple Claude instances to share and manage data with database-level locking for safe concurrent access.Last updated -JavaScript
- AsecurityAlicenseAqualityThis server enables interaction with Supabase PostgreSQL databases through the MCP protocol, allowing seamless integration with Cursor and Windsurf IDEs for secure and validated database management.Last updated -11649PythonApache 2.0