@aliyun-rds/supabase-mcp-server/README.md

MCP (Model Context Protocol) server for self-hosted Supabase instances. Allows AI assistants to interact with your self-hosted Supabase database.

# Aliyun RDS Supabase MCP Server

MCP (Model Context Protocol) server for Supabase instances running on Aliyun RDS. Enables AI assistants like Claude to interact with your Supabase instance hosted on Aliyun cloud infrastructure.

This project was adapted from the original work by [HenkDz](https://github.com/HenkDz) and is now maintained by the Aliyun RDS Research and Development Team.

## Alibaba Cloud Operation

This server is purpose-built for Supabase instances that run on Aliyun RDS AI. Key capabilities:

- Automatically fetches Supabase credentials from Alibaba Cloud OpenAPI
- Only requires Alibaba Cloud AccessKey (AK) and SecretKey (SK)
- Supports multiple Supabase instances with interactive selection
- No need to manually configure `anon-key`, `service-key`, or `jwt-secret`

## Features

This server exposes a rich set of tools for interacting with your Supabase instances running on Aliyun RDS:

*   **Alibaba Cloud Management** (Alibaba Cloud Mode only)
    *   `list_aliyun_supabase_instances`: Lists all Supabase instances from Alibaba Cloud RDS AI.
    *   `connect_to_supabase_instance`: Connects to a specific Supabase instance by name.
    *   `get_current_supabase_instance`: Shows the currently connected instance.
    *   `disconnect_supabase_instance`: Disconnects from the current 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 via RPC.
    *   `execute_sql`: Executes arbitrary SQL (Requires helper function in DB or direct DB access).
    *   `install_execute_sql_function`: Installs the `execute_sql` RPC function into the database.
    *   `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 using Supabase Admin API.
    *   `delete_auth_user`: Deletes a user using Supabase Admin API.
    *   `update_auth_user`: Updates user details using Supabase Admin API.
*   **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`).
*   **Documentation**
    *   `search_docs`: Searches Supabase official documentation using GraphQL queries.
*   **RAG Agent Tools** (when `--enable-rag-agent` is set)
    *   All RAG Agent tools are dynamically loaded and prefixed with `rag_` (e.g., `rag_check_health`, `rag_list_datasets`, `rag_get_dataset`, `rag_query_dataset`, `rag_query_multi_datasets`).
    *   These tools provide Retrieval-Augmented Generation capabilities for semantic search and document management.
    *   Available after connecting to a Supabase instance in Alibaba Cloud Mode.

*(Note: `get_logs` was initially planned but skipped due to implementation complexities observed in the upstream self-hosted environment).*

## How It Works

This MCP server works with AI assistant tools like Claude Desktop, Cursor, and other MCP-compatible applications. Once configured, these AI assistants can automatically use the tools provided by this server to interact with your Aliyun RDS-hosted Supabase instance.

For example, when you ask an AI assistant "List all tables in my database", it will:
1. Recognize it needs to use a database tool
2. Call the `list_tables` tool from this server
3. Execute the tool against your Supabase instance
4. Present the results in a human-readable format

## Setup and Installation

### Alibaba Cloud Mode Setup

#### Quick Start with npx

```bash
npx @aliyun-rds/supabase-mcp-server \
  --aliyun-ak YOUR_ACCESS_KEY_ID \
  --aliyun-sk YOUR_ACCESS_KEY_SECRET \
  --aliyun-region cn-hangzhou
```

**Important**: The `--aliyun-region` parameter is **required**. Without it, the API will return empty instance lists even though no error is reported. Common regions include:
- `cn-hangzhou` (China East 1)
- `cn-beijing` (China North 2)
- `cn-shanghai` (China East 2)
- `cn-shenzhen` (China South 1)

The CLI flag defines the default region for automatic discovery. When you need to inspect instances in other regions, call the `list_aliyun_supabase_instances` tool and provide its optional `region_id` argument (e.g., `cn-beijing`) to override the default for that request.

#### Configuration for Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "aliyun-supabase": {
      "command": "npx",
      "args": [
        "@aliyun-rds/supabase-mcp-server",
        "--aliyun-ak", "YOUR_ACCESS_KEY_ID",
        "--aliyun-sk", "YOUR_ACCESS_KEY_SECRET",
        "--aliyun-region", "cn-hangzhou"
      ]
    }
  }
}
```

**With RAG Agent integration:**

```json
{
  "mcpServers": {
    "aliyun-supabase": {
      "command": "npx",
      "args": [
        "@aliyun-rds/supabase-mcp-server",
        "--aliyun-ak", "YOUR_ACCESS_KEY_ID",
        "--aliyun-sk", "YOUR_ACCESS_KEY_SECRET",
        "--aliyun-region", "cn-hangzhou",
        "--enable-rag-agent"
      ]
    }
  }
}
```

Or use environment variables:

```json
{
  "mcpServers": {
    "aliyun-supabase": {
      "command": "npx",
      "args": [
        "@aliyun-rds/supabase-mcp-server",
        "--enable-rag-agent"
      ],
      "env": {
        "ALIYUN_ACCESS_KEY_ID": "YOUR_ACCESS_KEY_ID",
        "ALIYUN_ACCESS_KEY_SECRET": "YOUR_ACCESS_KEY_SECRET",
        "ALIYUN_REGION": "cn-hangzhou"
      }
    }
  }
}
```

#### Usage Workflow

1. **List instances**: Use `list_aliyun_supabase_instances` to see all your Supabase instances
2. **Connect**: Use `connect_to_supabase_instance` with the instance name
3. **Use tools**: Now you can use all Supabase tools (list_tables, execute_sql, etc.)
4. **Disconnect** (optional): Use `disconnect_supabase_instance` to switch instances

### Additional Installation Options

#### Install via Smithery

Install the Aliyun RDS 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
```

#### Global Installation

```bash
npm install -g @aliyun-rds/supabase-mcp-server
supabase-mcp \
  --aliyun-ak YOUR_ACCESS_KEY_ID \
  --aliyun-sk YOUR_ACCESS_KEY_SECRET \
  --aliyun-region cn-hangzhou
```

## Configuration

The server now relies exclusively on Alibaba Cloud credentials. Provide them via command-line arguments or environment variables (CLI arguments take precedence). Once authenticated, the MCP server automatically retrieves the Supabase URL, anon key, service key, database connection string, and JWT secret for the selected Aliyun RDS instance—no manual entry is needed.

### Required Parameters

*   `--aliyun-ak <key>` or `ALIYUN_ACCESS_KEY_ID=<key>`: Alibaba Cloud Access Key ID.
*   `--aliyun-sk <secret>` or `ALIYUN_ACCESS_KEY_SECRET=<secret>`: Alibaba Cloud Access Key Secret.
*   `--aliyun-region <region>` or `ALIYUN_REGION=<region>`: **Mandatory** region where your Supabase instances live (e.g., `cn-hangzhou`, `cn-beijing`). Without this, the OpenAPI call cannot list instances. This value becomes the default region, but tools like `list_aliyun_supabase_instances` accept a `region_id` parameter so you can query other regions on demand.

### Optional Parameters

*   `--tools-config <path>`: JSON file specifying which tools to enable (whitelist). Format: `{"enabledTools": ["tool_name_1", "tool_name_2"]}`.
*   `--enable-rag-agent` or `ENABLE_RAG_AGENT=true`: Enable RAG Agent MCP integration. When enabled, the server resolves the Supabase host/port from the selected instance and uses the retrieved anon key as the API key for rag-agent; no manual `--url` or `--anon-key` flags are needed.

Legacy CLI options (`--url`, `--anon-key`, `--service-key`, `--db-url`, `--jwt-secret`) have been removed from the user-facing surface because Aliyun RDS now supplies those details automatically.

### RAG Agent Integration

This server can integrate with [rag-agent-mcp](https://pypi.org/project/rag-agent-mcp/) to provide RAG (Retrieval-Augmented Generation) capabilities alongside your Supabase database tools.

**How it works:**
- When `--enable-rag-agent` is set, the server automatically connects to a rag-agent MCP server after you select an Aliyun RDS Supabase instance.
- The Supabase host/port is derived from the instance metadata returned by Aliyun OpenAPI.
- The anon key retrieved for the connected instance is reused as the API key for rag-agent (no manual secret sharing required).
- All rag-agent tools are prefixed with `rag_` to avoid naming conflicts (e.g., `rag_create_collection`, `rag_add_documents`, `rag_query`).

**Example configuration:**
```bash
npx @aliyun-rds/supabase-mcp-server \
  --aliyun-ak YOUR_ACCESS_KEY_ID \
  --aliyun-sk YOUR_ACCESS_KEY_SECRET \
  --aliyun-region cn-hangzhou \
  --enable-rag-agent
```

**Requirements:**
- `uvx` must be installed on your system
- `rag-agent-mcp` package must be available via `uvx`
- The rag-agent service must be reachable at the host/port reported by your Supabase instance

**Behavior Notes:**
- RAG Agent tools are advertised at startup but become fully functional only after running `connect_to_supabase_instance`.
- Because the host/port comes from Supabase metadata, ensure your Aliyun credentials can fetch instance connection details.

### Important Notes:

*   **`execute_sql` Helper Function:** Many tools rely on a `public.execute_sql` function for secure SQL execution via RPC. After you connect to an Aliyun RDS instance, the server checks for this function and—if your AK/SK grants the required privileges—automatically creates it and assigns permissions when missing.
*   **Direct Database Access:** Tools that touch privileged schemas (`auth`, `storage`) or `pg_catalog` still require direct database connectivity. The connection string is pulled from Aliyun; ensure your credentials can retrieve it or those tools will be unavailable.
*   **Database URL Special Characters:** When Aliyun returns database URLs containing characters like `#` or `$`, the server automatically URL-encodes them (`#` → `%23`, `$` → `%24`). The `@` symbol remains unescaped because it separates credentials from the hostname.

## Using with AI Assistant Tools

### Cursor

1.  Create or open the file `.cursor/mcp.json` in your project root.
2.  Add the following configuration:

    ```json
    {
      "mcpServers": {
        "aliyun-supabase": {
          "command": "npx",
          "args": [
            "@aliyun-rds/supabase-mcp-server",
            "--aliyun-ak",
            "<your-access-key-id>",
            "--aliyun-sk",
            "<your-access-key-secret>",
            "--aliyun-region",
            "cn-hangzhou",
            "--enable-rag-agent"
          ],
          "env": {
            // Optional: whitelist tools or toggle features
            "TOOLS_CONFIG": "<path-to-tools-config.json>",
            "ENABLE_RAG_AGENT": "true"
          }
        }
      }
    }
    ```

**Important Notes for RAG Agent:**
- RAG Agent tools stay inactive until you call `connect_to_supabase_instance` and select an Aliyun RDS Supabase project.
- Switching instances automatically re-initializes the rag-agent connection with the new host/port.
- All RAG Agent tools are prefixed with `rag_` (e.g., `rag_create_collection`, `rag_add_documents`, `rag_query`).

### 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": "Aliyun Supabase",
      "command": "npx",
      "args": [
        "@aliyun-rds/supabase-mcp-server",
        "--aliyun-ak",
        "YOUR_ACCESS_KEY_ID",
        "--aliyun-sk",
        "YOUR_ACCESS_KEY_SECRET",
        "--aliyun-region",
        "cn-hangzhou"
      ]
    }
    ```

### Other MCP-Compatible Tools

Most MCP-compatible tools follow similar configuration patterns. The general format is:
- Command: `npx`
- Arguments: `[@aliyun-rds/supabase-mcp-server, --aliyun-ak, YOUR_ACCESS_KEY_ID, --aliyun-sk, YOUR_ACCESS_KEY_SECRET, --aliyun-region, YOUR_REGION, ...]`

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