Supabase Automation

1---
2name: supabase-automation
3description: "Automate Supabase database queries, table management, project administration, storage, edge functions, and SQL execution via Rube MCP (Composio). Always search tools first for current schemas."
4requires:
5  mcp: [rube]
6---
7 
8# Supabase Automation via Rube MCP
9 
10Automate Supabase operations including database queries, table schema inspection, SQL execution, project and organization management, storage buckets, edge functions, and service health monitoring through Composio's Supabase toolkit.
11 
12## Prerequisites
13 
14- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
15- Active Supabase connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `supabase`
16- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
17 
18## Setup
19 
20**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
21 
22 
231. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
242. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `supabase`
253. If connection is not ACTIVE, follow the returned auth link to complete Supabase authentication
264. Confirm connection status shows ACTIVE before running any workflows
27 
28## Core Workflows
29 
30### 1. Query and Manage Database Tables
31 
32**When to use**: User wants to read data from tables, inspect schemas, or perform CRUD operations
33 
34**Tool sequence**:
351. `SUPABASE_LIST_ALL_PROJECTS` - List projects to find the target project_ref [Prerequisite]
362. `SUPABASE_LIST_TABLES` - List all tables and views in the database [Prerequisite]
373. `SUPABASE_GET_TABLE_SCHEMAS` - Get detailed column types, constraints, and relationships [Prerequisite for writes]
384. `SUPABASE_SELECT_FROM_TABLE` - Query rows with filtering, sorting, and pagination [Required for reads]
395. `SUPABASE_BETA_RUN_SQL_QUERY` - Execute arbitrary SQL for complex queries, inserts, updates, or deletes [Required for writes]
40 
41**Key parameters for SELECT_FROM_TABLE**:
42- `project_ref`: 20-character lowercase project reference
43- `table`: Table or view name to query
44- `select`: Comma-separated column list (supports nested selections and JSON paths like `profile->avatar_url`)
45- `filters`: Array of filter objects with `column`, `operator`, `value`
46- `order`: Sort expression like `created_at.desc`
47- `limit`: Max rows to return (minimum 1)
48- `offset`: Rows to skip for pagination
49 
50**PostgREST filter operators**:
51- `eq`, `neq`: Equal / not equal
52- `gt`, `gte`, `lt`, `lte`: Comparison operators
53- `like`, `ilike`: Pattern matching (case-sensitive / insensitive)
54- `is`: IS check (for null, true, false)
55- `in`: In a list of values
56- `cs`, `cd`: Contains / contained by (arrays)
57- `fts`, `plfts`, `phfts`, `wfts`: Full-text search variants
58 
59**Key parameters for RUN_SQL_QUERY**:
60- `ref`: Project reference (20 lowercase letters, pattern `^[a-z]{20}$`)
61- `query`: Valid PostgreSQL SQL statement
62- `read_only`: Boolean to force read-only transaction (safer for SELECTs)
63 
64**Pitfalls**:
65- `project_ref` must be exactly 20 lowercase letters (a-z only, no numbers or hyphens)
66- `SELECT_FROM_TABLE` is read-only; use `RUN_SQL_QUERY` for INSERT, UPDATE, DELETE operations
67- For PostgreSQL array columns (text[], integer[]), use `ARRAY['item1', 'item2']` or `'{"item1", "item2"}'` syntax, NOT JSON array syntax `'["item1", "item2"]'`
68- SQL identifiers that are case-sensitive must be double-quoted in queries
69- Complex DDL operations may timeout (~60 second limit); break into smaller queries
70- ERROR 42P01 "relation does not exist" usually means unquoted case-sensitive identifiers
71- ERROR 42883 "function does not exist" means you are calling non-standard helpers; prefer information_schema queries
72 
73### 2. Manage Projects and Organizations
74 
75**When to use**: User wants to list projects, inspect configurations, or manage organizations
76 
77**Tool sequence**:
781. `SUPABASE_LIST_ALL_ORGANIZATIONS` - List all organizations (IDs and names) [Required]
792. `SUPABASE_GETS_INFORMATION_ABOUT_THE_ORGANIZATION` - Get detailed org info by slug [Optional]
803. `SUPABASE_LIST_MEMBERS_OF_AN_ORGANIZATION` - List org members with roles and MFA status [Optional]
814. `SUPABASE_LIST_ALL_PROJECTS` - List all projects with metadata [Required]
825. `SUPABASE_GETS_PROJECT_S_POSTGRES_CONFIG` - Get database configuration [Optional]
836. `SUPABASE_GETS_PROJECT_S_AUTH_CONFIG` - Get authentication configuration [Optional]
847. `SUPABASE_GET_PROJECT_API_KEYS` - Get API keys (sensitive -- handle carefully) [Optional]
858. `SUPABASE_GETS_PROJECT_S_SERVICE_HEALTH_STATUS` - Check service health [Optional]
86 
87**Key parameters**:
88- `ref`: Project reference for project-specific tools
89- `slug`: Organization slug (URL-friendly identifier) for org tools
90- `services`: Array of services for health check: `auth`, `db`, `db_postgres_user`, `pg_bouncer`, `pooler`, `realtime`, `rest`, `storage`
91 
92**Pitfalls**:
93- `LIST_ALL_ORGANIZATIONS` returns both `id` and `slug`; `LIST_MEMBERS_OF_AN_ORGANIZATION` expects `slug`, not `id`
94- `GET_PROJECT_API_KEYS` returns live secrets -- NEVER log, display, or persist full key values
95- `GETS_PROJECT_S_SERVICE_HEALTH_STATUS` requires a non-empty `services` array; empty array causes invalid_request error
96- Config tools may return 401/403 if token lacks required scope; handle gracefully rather than failing the whole workflow
97 
98### 3. Inspect Database Schema
99 
100**When to use**: User wants to understand table structure, columns, constraints, or generate types
101 
102**Tool sequence**:
1031. `SUPABASE_LIST_ALL_PROJECTS` - Find the target project [Prerequisite]
1042. `SUPABASE_LIST_TABLES` - Enumerate all tables and views with metadata [Required]
1053. `SUPABASE_GET_TABLE_SCHEMAS` - Get detailed schema for specific tables [Required]
1064. `SUPABASE_GENERATE_TYPE_SCRIPT_TYPES` - Generate TypeScript types from schema [Optional]
107 
108**Key parameters for LIST_TABLES**:
109- `project_ref`: Project reference
110- `schemas`: Array of schema names to search (e.g., `["public"]`); omit for all non-system schemas
111- `include_views`: Include views alongside tables (default true)
112- `include_metadata`: Include row count estimates and sizes (default true)
113- `include_system_schemas`: Include pg_catalog, information_schema, etc. (default false)
114 
115**Key parameters for GET_TABLE_SCHEMAS**:
116- `project_ref`: Project reference
117- `table_names`: Array of table names (max 20 per request); supports schema prefix like `public.users`, `auth.users`
118- `include_relationships`: Include foreign key info (default true)
119- `include_indexes`: Include index info (default true)
120- `exclude_null_values`: Cleaner output by hiding null fields (default true)
121 
122**Key parameters for GENERATE_TYPE_SCRIPT_TYPES**:
123- `ref`: Project reference
124- `included_schemas`: Comma-separated schema names (default `"public"`)
125 
126**Pitfalls**:
127- Table names without schema prefix assume `public` schema
128- `row_count` and `size_bytes` from LIST_TABLES may be null for views or recently created tables; treat as unknown, not zero
129- GET_TABLE_SCHEMAS has a max of 20 tables per request; batch if needed
130- TypeScript types include all tables in specified schemas; cannot filter individual tables
131 
132### 4. Manage Edge Functions
133 
134**When to use**: User wants to list, inspect, or work with Supabase Edge Functions
135 
136**Tool sequence**:
1371. `SUPABASE_LIST_ALL_PROJECTS` - Find the project reference [Prerequisite]
1382. `SUPABASE_LIST_ALL_FUNCTIONS` - List all edge functions with metadata [Required]
1393. `SUPABASE_RETRIEVE_A_FUNCTION` - Get detailed info for a specific function [Optional]
140 
141**Key parameters**:
142- `ref`: Project reference
143- Function slug for RETRIEVE_A_FUNCTION
144 
145**Pitfalls**:
146- `LIST_ALL_FUNCTIONS` returns metadata only, not function code or logs
147- `created_at` and `updated_at` may be epoch milliseconds; convert to human-readable timestamps
148- These tools cannot create or deploy edge functions; they are read-only inspection tools
149- Permission errors may occur without org/project admin rights
150 
151### 5. Manage Storage Buckets
152 
153**When to use**: User wants to list storage buckets or manage file storage
154 
155**Tool sequence**:
1561. `SUPABASE_LIST_ALL_PROJECTS` - Find the project reference [Prerequisite]
1572. `SUPABASE_LISTS_ALL_BUCKETS` - List all storage buckets [Required]
158 
159**Key parameters**:
160- `ref`: Project reference
161 
162**Pitfalls**:
163- `LISTS_ALL_BUCKETS` returns bucket list only, not bucket contents or access policies
164- For file uploads, `SUPABASE_RESUMABLE_UPLOAD_SIGN_OPTIONS_WITH_ID` handles CORS preflight for TUS resumable uploads only
165- Direct file operations may require using `proxy_execute` with the Supabase storage API
166 
167## Common Patterns
168 
169### ID Resolution
170- **Project reference**: `SUPABASE_LIST_ALL_PROJECTS` -- extract `ref` field (20 lowercase letters)
171- **Organization slug**: `SUPABASE_LIST_ALL_ORGANIZATIONS` -- use `slug` (not `id`) for downstream org tools
172- **Table names**: `SUPABASE_LIST_TABLES` -- enumerate available tables before querying
173- **Schema discovery**: `SUPABASE_GET_TABLE_SCHEMAS` -- inspect columns and constraints before writes
174 
175### Pagination
176- `SUPABASE_SELECT_FROM_TABLE`: Uses `offset` + `limit` pagination. Increment offset by limit until fewer rows than limit are returned.
177- `SUPABASE_LIST_ALL_PROJECTS`: May paginate for large accounts; follow cursors/pages until exhausted.
178- `SUPABASE_LIST_TABLES`: May paginate for large databases.
179 
180### SQL Best Practices
181- Always use `SUPABASE_GET_TABLE_SCHEMAS` or `SUPABASE_LIST_TABLES` before writing SQL
182- Use `read_only: true` for SELECT queries to prevent accidental mutations
183- Quote case-sensitive identifiers: `SELECT * FROM "MyTable"` not `SELECT * FROM MyTable`
184- Use PostgreSQL array syntax for array columns: `ARRAY['a', 'b']` not `['a', 'b']`
185- Break complex DDL into smaller statements to avoid timeouts
186 
187## Known Pitfalls
188 
189### ID Formats
190- Project references are exactly 20 lowercase letters (a-z): pattern `^[a-z]{20}$`
191- Organization identifiers come as both `id` (UUID) and `slug` (URL-friendly string); tools vary in which they accept
192- `LIST_MEMBERS_OF_AN_ORGANIZATION` requires `slug`, not `id`
193 
194### SQL Execution
195- `BETA_RUN_SQL_QUERY` has ~60 second timeout for complex operations
196- PostgreSQL array syntax required: `ARRAY['item']` or `'{"item"}'`, NOT JSON syntax `'["item"]'`
197- Case-sensitive identifiers must be double-quoted in SQL
198- ERROR 42P01: relation does not exist (check quoting and schema prefix)
199- ERROR 42883: function does not exist (use information_schema instead of custom helpers)
200 
201### Sensitive Data
202- `GET_PROJECT_API_KEYS` returns service-role keys -- NEVER expose full values
203- Auth config tools exclude secrets but may still contain sensitive configuration
204- Always mask or truncate API keys in output
205 
206### Schema Metadata
207- `row_count` and `size_bytes` from `LIST_TABLES` can be null; do not treat as zero
208- System schemas are excluded by default; set `include_system_schemas: true` to see them
209- Views appear alongside tables unless `include_views: false`
210 
211### Rate Limits and Permissions
212- Enrichment tools (API keys, configs) may return 401/403 without proper scopes; skip gracefully
213- Large table listings may require pagination
214- `GETS_PROJECT_S_SERVICE_HEALTH_STATUS` fails with empty `services` array -- always specify at least one
215 
216## Quick Reference
217 
218| Task | Tool Slug | Key Params |
219|------|-----------|------------|
220| List organizations | `SUPABASE_LIST_ALL_ORGANIZATIONS` | (none) |
221| Get org info | `SUPABASE_GETS_INFORMATION_ABOUT_THE_ORGANIZATION` | `slug` |
222| List org members | `SUPABASE_LIST_MEMBERS_OF_AN_ORGANIZATION` | `slug` |
223| List projects | `SUPABASE_LIST_ALL_PROJECTS` | (none) |
224| List tables | `SUPABASE_LIST_TABLES` | `project_ref`, `schemas` |
225| Get table schemas | `SUPABASE_GET_TABLE_SCHEMAS` | `project_ref`, `table_names` |
226| Query table | `SUPABASE_SELECT_FROM_TABLE` | `project_ref`, `table`, `select`, `filters` |
227| Run SQL | `SUPABASE_BETA_RUN_SQL_QUERY` | `ref`, `query`, `read_only` |
228| Generate TS types | `SUPABASE_GENERATE_TYPE_SCRIPT_TYPES` | `ref`, `included_schemas` |
229| Postgres config | `SUPABASE_GETS_PROJECT_S_POSTGRES_CONFIG` | `ref` |
230| Auth config | `SUPABASE_GETS_PROJECT_S_AUTH_CONFIG` | `ref` |
231| Get API keys | `SUPABASE_GET_PROJECT_API_KEYS` | `ref` |
232| Service health | `SUPABASE_GETS_PROJECT_S_SERVICE_HEALTH_STATUS` | `ref`, `services` |
233| List edge functions | `SUPABASE_LIST_ALL_FUNCTIONS` | `ref` |
234| Get edge function | `SUPABASE_RETRIEVE_A_FUNCTION` | `ref`, function slug |
235| List storage buckets | `SUPABASE_LISTS_ALL_BUCKETS` | `ref` |
236| List DB branches | `SUPABASE_LIST_ALL_DATABASE_BRANCHES` | `ref` |
237