UBOS Asset Marketplace: Self-Hosted Supabase MCP Server - Unleash the Power of Local Development

In today’s rapidly evolving software development landscape, the ability to manage and interact with databases efficiently is paramount. For developers leveraging the power of Supabase, a self-hosted Model Context Protocol (MCP) server can be a game-changer. The UBOS Asset Marketplace now offers a robust solution that bridges the gap between your self-hosted Supabase instances and your favorite development tools, empowering you with seamless database introspection, management, and interaction directly from your development environment.

What is MCP and Why Does it Matter?

Before diving into the specifics of the Self-Hosted Supabase MCP Server, it’s crucial to understand the role of the Model Context Protocol (MCP). MCP is an open standard that defines how applications can provide context to Large Language Models (LLMs). In essence, it allows AI models to access and interact with external data sources and tools. An MCP server acts as the intermediary, facilitating communication between AI clients and backend systems.

For developers, this means being able to leverage AI-powered tools directly within their development workflows. Imagine being able to query your database schema, generate type definitions, or even apply migrations using natural language commands. This is the power of MCP.

The Challenge of Self-Hosted Supabase

Supabase provides a powerful open-source alternative to Firebase, offering a comprehensive suite of tools for building scalable and performant applications. While Supabase offers a cloud-hosted solution, many developers prefer the control and flexibility of self-hosting. However, self-hosting introduces its own set of challenges, particularly when it comes to integrating with MCP-based tools.

The official Supabase cloud MCP server is designed for managing multiple projects within the Supabase cloud environment. It often includes complexities related to cloud-specific APIs and multi-project management, which are not relevant to a single-project, self-hosted setup. This is where the UBOS Asset Marketplace’s Self-Hosted Supabase MCP Server steps in.

Introducing the Self-Hosted Supabase MCP Server

The Self-Hosted Supabase MCP Server is a purpose-built solution designed to address the specific needs of developers using self-hosted Supabase instances. It provides a streamlined and focused implementation of the MCP protocol, tailored for single-project environments.

This server was meticulously crafted from the ground up, drawing upon valuable lessons learned from adapting the official Supabase cloud MCP server. The result is a minimal, yet powerful, solution that offers a seamless experience for developers working with self-hosted Supabase projects.

Key Features and Benefits

• Seamless Integration: Effortlessly connect your self-hosted Supabase instance with MCP-based tools, unlocking a new level of productivity and efficiency.
• Database Introspection: Gain deep insights into your database schema, data, and statistics directly from your development environment.
• Simplified Management: Manage database migrations, authentication users, and storage buckets with ease.
• Enhanced Security: Maintain complete control over your data and infrastructure, ensuring the highest levels of security and privacy.
• Streamlined Workflow: Automate repetitive tasks and focus on building innovative features.
• Open Source and Customizable: Built on open standards and fully customizable to meet your specific needs.

Core Functionality: Implemented Tools

The Self-Hosted Supabase MCP Server exposes a comprehensive set of tools to MCP clients, enabling a wide range of database-related tasks:

• Schema & Migrations:
  • list_tables: Enumerate all tables within the database schemas.
  • list_extensions: Discover installed PostgreSQL extensions.
  • list_migrations: Review applied Supabase migrations.
  • apply_migration: Execute a SQL migration script.
• Database Operations & Stats:
  • execute_sql: Execute custom SQL queries (via RPC or direct connection).
  • get_database_connections: Monitor active database connections using pg_stat_activity.
  • get_database_stats: Collect database statistics from pg_stat_*.
• Project Configuration & Keys:
  • get_project_url: Retrieve the configured Supabase URL.
  • get_anon_key: Access the configured Supabase anonymous key.
  • get_service_key: Obtain the configured Supabase service role key (if provided).
  • verify_jwt_secret: Validate the JWT secret configuration and display a preview.
• Development & Extension Tools:
  • generate_typescript_types: Automatically generate TypeScript types from the database schema.
  • rebuild_hooks: Attempt to restart the pg_net worker (if used).
• Auth User Management:
  • list_auth_users: List users from the auth.users table.
  • get_auth_user: Retrieve detailed information for a specific user.
  • create_auth_user: Create new users (requires direct DB access and involves insecure password handling).
  • delete_auth_user: Delete users (requires direct DB access).
  • update_auth_user: Modify user details (requires direct DB access and involves insecure password handling).
• Storage Insights:
  • list_storage_buckets: Enumerate all storage buckets.
  • list_storage_objects: List objects within a specific bucket.
• Realtime Inspection:
  • list_realtime_publications: List PostgreSQL publications (typically supabase_realtime).

Getting Started: Installation and Configuration

Setting up the Self-Hosted Supabase MCP Server is a straightforward process. Here’s a step-by-step guide:

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

Installation Steps

1. Clone the repository: bash git clone cd self-hosted-supabase-mcp

2. Install dependencies: bash npm install

3. Build the project: bash 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 Configuration 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 and Integration with MCP Clients

To run the server, use the following command:

bash node dist/index.js --url http://localhost:8000 --anon-key --db-url postgresql://postgres:password@localhost:5432/postgres [–service-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 or Visual Studio Code with Copilot). The client will connect to the server’s stdio stream to list and call the available tools.

Client Configuration Examples

Here are some examples of how to configure popular MCP clients to use this self-hosted server:

Cursor

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

2. Add the following configuration:

   { “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”, “”, // e.g., “http://localhost:8000” “–anon-key”, “”, // Optional - Add these if needed by the tools you use “–service-key”, “”, “–db-url”, “”, // e.g., “postgresql://postgres:password@host:port/postgres” “–jwt-secret”, “”, // Optional - Whitelist specific tools “–tools-config”, “<path-to-your-mcp-tools.json>” // e.g., “./mcp-tools.json” ] } } }

Visual Studio Code (Copilot)

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

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

2. Add the following configuration:

   { “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 } } } }

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.

The UBOS Advantage: Orchestrating AI Agents for Business

The Self-Hosted Supabase MCP Server is a valuable asset for developers building applications on Supabase. But its true potential is unlocked when integrated with the UBOS platform.

UBOS is a full-stack AI Agent development platform designed to bring the power of AI Agents to every business department. With UBOS, you can:

• Orchestrate AI Agents: Design and manage complex workflows involving multiple AI Agents.
• Connect to Enterprise Data: Seamlessly integrate AI Agents with your existing data sources, including databases, APIs, and files.
• Build Custom AI Agents: Create specialized AI Agents tailored to your specific business needs.
• Leverage Multi-Agent Systems: Develop sophisticated AI solutions that combine the strengths of multiple AI Agents.

By combining the Self-Hosted Supabase MCP Server with the UBOS platform, you can create powerful AI-driven applications that leverage your Supabase data and integrate seamlessly into your existing business processes. Imagine an AI Agent that automatically analyzes your Supabase database, identifies potential security vulnerabilities, and generates remediation recommendations. Or an AI Agent that monitors your Supabase storage buckets for unusual activity and alerts you to potential data breaches.

The possibilities are endless.

Conclusion

The UBOS Asset Marketplace’s Self-Hosted Supabase MCP Server is a crucial tool for developers seeking to maximize the potential of their self-hosted Supabase instances. By bridging the gap between your local database and AI-powered development tools, this server empowers you with seamless database introspection, management, and interaction. When combined with the UBOS platform, the Self-Hosted Supabase MCP Server unlocks a new level of AI-driven innovation, enabling you to build powerful applications that transform your business.

Embrace the future of software development. Embrace the power of UBOS and the Self-Hosted Supabase MCP Server.