npm package: @lemontreen/rds-supabase-mcp-server
Description: MCP (Model Context Protocol) server for self-hosted Supabase instances. Allows AI assistants to interact with your self-hosted Supabase database.
Author: HenkDz
Latest version: 1.0.0

# 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](https://github.com/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:

```bash
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](https://smithery.ai/server/@HenkDz/selfhosted-supabase-mcp):

```bash
npx -y @smithery/cli install @HenkDz/selfhosted-supabase-mcp --client claude
```

### Method 3: Global Installation

Install the package globally:

```bash
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:**
    ```bash
    git clone <repository-url>
    cd selfhosted-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 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:

```bash
# 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:

    ```json
    {
      "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:

    ```json
    {
      "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](LICENSE) file for details.

Originally developed by [HenkDz](https://github.com/HenkDz), now maintained by lemontreen.