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

Authentication Modes & Permission Levels

The server supports three authentication modes with automatic tool filtering:

• Mode 1 – Alibaba Cloud Multi-Instance (AuthMode aliyun, permission full)
  Use --aliyun-ak, --aliyun-sk, and --aliyun-region to discover and manage multiple Aliyun RDS Supabase instances. Grants access to all tools, including Aliyun management tools.
• Mode 2 – Single Instance Admin (AuthMode admin, permission admin)
  Use --supabase-url, --supabase-anon-key, and --supabase-service-role-key for a single project. Admin-only tools stay available; Aliyun management tools are hidden.
• Mode 3 – Single Instance User (AuthMode user, permission user)
  Use --supabase-url, --supabase-anon-key, plus --supabase-user-email and --supabase-user-password. Runs under the user’s RLS scope; admin tools and Aliyun management tools are disabled.

Tool visibility is enforced automatically:

• Aliyun-only tools (e.g., list_aliyun_supabase_instances, connect_to_supabase_instance, get_current_supabase_instance, disconnect_supabase_instance) require full permissions.
• Admin-only tools (auth management, get_service_key, verify_jwt_secret, install_execute_sql_function, rebuild_hooks) require full or admin permissions.

Mode selection priority: if multiple configurations are provided, the server picks Aliyun first; if Aliyun is absent and user credentials are complete, user mode is selected; otherwise admin mode is used. A warning is logged when multiple modes are detected.

Setup and Installation

Alibaba Cloud Mode Setup

Quick Start with npx

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:

{
  "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:

{
  "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:

{
  "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

Single Instance Admin Mode Setup

npx @aliyun-rds/supabase-mcp-server \
  --supabase-url https://<your-project>.supabase.co \
  --supabase-anon-key <anon-key> \
  --supabase-service-role-key <service-role-key> \
  [--db-url <postgres-connection-string>] \
  [--jwt-secret <jwt-secret>] \
  [--enable-rag-agent]

Environment variable alternative:

SUPABASE_URL=https://<your-project>.supabase.co \
SUPABASE_ANON_KEY=<anon-key> \
SUPABASE_SERVICE_ROLE_KEY=<service-role-key> \
supabase-mcp

Claude Desktop / Cursor JSON 示例：

{
  "mcpServers": {
    "supabase-admin": {
      "command": "npx",
      "args": [
        "@aliyun-rds/supabase-mcp-server",
        "--supabase-url", "https://<your-project>.supabase.co",
        "--supabase-anon-key", "<anon-key>",
        "--supabase-service-role-key", "<service-role-key>"
      ]
    }
  }
}

Single Instance User Mode Setup (RLS Restricted)

npx @aliyun-rds/supabase-mcp-server \
  --supabase-url https://<your-project>.supabase.co \
  --supabase-anon-key <anon-key> \
  --supabase-user-email <user-email> \
  --supabase-user-password <user-password> \
  [--enable-rag-agent]

Environment variable alternative:

SUPABASE_URL=https://<your-project>.supabase.co \
SUPABASE_ANON_KEY=<anon-key> \
SUPABASE_USER_EMAIL=<user-email> \
SUPABASE_USER_PASSWORD=<user-password> \
supabase-mcp

Claude Desktop / Cursor JSON 示例：

{
  "mcpServers": {
    "supabase-user": {
      "command": "npx",
      "args": [
        "@aliyun-rds/supabase-mcp-server",
        "--supabase-url", "https://<your-project>.supabase.co",
        "--supabase-anon-key", "<anon-key>",
        "--supabase-user-email", "<user-email>",
        "--supabase-user-password", "<user-password>"
      ]
    }
  }
}

Additional Installation Options

Global Installation

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

Choose one configuration path. CLI flags override environment variables.

Mode 1 — Alibaba Cloud Multi-Instance (permission: full)

Required:

• --aliyun-ak <key> or ALIYUN_ACCESS_KEY_ID=<key>
• --aliyun-sk <secret> or ALIYUN_ACCESS_KEY_SECRET=<secret>
• --aliyun-region <region> or ALIYUN_REGION=<region> (e.g., cn-hangzhou, cn-beijing; required for discovery)

Behavior: pulls Supabase URL/keys/DB URL/JWT secret from Aliyun for the selected instance.

Mode 2 — Single Instance Admin (permission: admin)

Required:

• --supabase-url <url> or SUPABASE_URL
• --supabase-anon-key <key> or SUPABASE_ANON_KEY
• --supabase-service-role-key <key> or SUPABASE_SERVICE_ROLE_KEY

Optional:

• --db-url <postgres-connection-string> or DB_URL
• --jwt-secret <secret> or JWT_SECRET

Legacy flag aliases are still accepted: --url, --anon-key, --service-key, --db-url, --jwt-secret.

Mode 3 — Single Instance User (permission: user, RLS enforced)

Required:

• --supabase-url <url> or SUPABASE_URL
• --supabase-anon-key <key> or SUPABASE_ANON_KEY
• --supabase-user-email <email> or SUPABASE_USER_EMAIL
• --supabase-user-password <password> or SUPABASE_USER_PASSWORD

Behavior: operates under the provided user's RLS policies; admin-only and Aliyun management tools are filtered out.

Common Options

• --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.
• --workspace-path <path>: Workspace root for file operations (optional).

RAG Agent Integration

This server can integrate with 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:

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 one of the following configurations based on your authentication mode:

   Mode 1 (Aliyun multi-instance, permission: full)
   Grants all tools, including Aliyun management.

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

   Mode 2 (Single instance admin, permission: admin)
   Admin tools available; Aliyun management tools hidden.

   {
     "mcpServers": {
       "supabase-admin": {
         "command": "npx",
         "args": [
           "@aliyun-rds/supabase-mcp-server",
           "--supabase-url", "https://<your-project>.supabase.co",
           "--supabase-anon-key", "<anon-key>",
           "--supabase-service-role-key", "<service-role-key>",
           "--enable-rag-agent"
         ]
       }
     }
   }

   Mode 3 (Single instance user, permission: user, RLS enforced)
   Runs under user RLS; admin/Aliyun tools disabled.

   {
     "mcpServers": {
       "supabase-user": {
         "command": "npx",
         "args": [
           "@aliyun-rds/supabase-mcp-server",
           "--supabase-url", "https://<your-project>.supabase.co",
           "--supabase-anon-key", "<anon-key>",
           "--supabase-user-email", "<user-email>",
           "--supabase-user-password", "<user-password>",
           "--enable-rag-agent"
         ]
       }
     }
   }

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, open Settings → Developer → enable "Custom MCP Servers", then add one configuration matching your mode:

Mode 1 (Aliyun, permission: full)

{
  "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",
    "--enable-rag-agent"
  ]
}

Mode 2 (Single instance admin, permission: admin)

{
  "name": "Supabase Admin",
  "command": "npx",
  "args": [
    "@aliyun-rds/supabase-mcp-server",
    "--supabase-url", "https://<your-project>.supabase.co",
    "--supabase-anon-key", "<anon-key>",
    "--supabase-service-role-key", "<service-role-key>",
    "--enable-rag-agent"
  ]
}

Mode 3 (Single instance user, permission: user, RLS enforced)

{
  "name": "Supabase User",
  "command": "npx",
  "args": [
    "@aliyun-rds/supabase-mcp-server",
    "--supabase-url", "https://<your-project>.supabase.co",
    "--supabase-anon-key", "<anon-key>",
    "--supabase-user-email", "<user-email>",
    "--supabase-user-password", "<user-password>",
    "--enable-rag-agent"
  ]
}

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 file for details.

Originally developed by HenkDz, now maintained by Aliyun RDS.