From 6fb521dd3661a6f153f871c4408fffe7fd460ca4 Mon Sep 17 00:00:00 2001 From: Jack Wotherspoon Date: Tue, 11 Nov 2025 12:00:46 -0500 Subject: [PATCH 1/7] feat: add Gemini CLI extension for Supabase --- SUPABASE.md | 11 +++++++++++ gemini-extension.json | 11 +++++++++++ 2 files changed, 22 insertions(+) create mode 100644 SUPABASE.md create mode 100644 gemini-extension.json diff --git a/SUPABASE.md b/SUPABASE.md new file mode 100644 index 00000000..d09fea83 --- /dev/null +++ b/SUPABASE.md @@ -0,0 +1,11 @@ +# Supabase extension for Gemini CLI + +## Overview + +This extension allows you to access your Supabase projects and perform tasks like managing tables, fetching config, and querying data. + +## Best Practices + +## Troubleshooting + + diff --git a/gemini-extension.json b/gemini-extension.json new file mode 100644 index 00000000..adb765bd --- /dev/null +++ b/gemini-extension.json @@ -0,0 +1,11 @@ +{ + "name": "supabase", + "description": "Access your Supabase projects and perform tasks like managing tables, fetching config, and querying data.", + "version": "0.5.9", + "contextFileName": "SUPABASE.md", + "mcpServers": { + "supabase": { + "httpUrl": "https://mcp.supabase.com/mcp" + } + } +} From c077357d5e4aac815fa220faa60db425d67da010 Mon Sep 17 00:00:00 2001 From: dshukertjr Date: Wed, 12 Nov 2025 12:05:49 +0900 Subject: [PATCH 2/7] Update SUPABASE.md with more context. --- SUPABASE.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/SUPABASE.md b/SUPABASE.md index d09fea83..116108fe 100644 --- a/SUPABASE.md +++ b/SUPABASE.md @@ -4,8 +4,32 @@ This extension allows you to access your Supabase projects and perform tasks like managing tables, fetching config, and querying data. +**Key capabilities**: Execute SQL, manage migrations, deploy functions, generate TypeScript types, access logs, and search documentation. + ## Best Practices +**Security defaults** +- Use read-only mode (`?read_only=true`) to prevent accidental writes +- Scope to specific projects (`?project_ref=`) to limit access +- Limit tool access with feature groups (`?features=docs%2Caccount%2Cdatabase%2Cdebugging%2Cdevelopment`) + - Available groups: `account`, `docs`, `database`, `debugging`, `development`, `functions`, `storage`, `branching` +- Avoid connecting to production databases even in read-only mode + +**Schema management** +- Use `apply_migration` for schema changes (CREATE/ALTER/DROP tables) - these are tracked +- Use `execute_sql` for queries and data operations (SELECT/INSERT/UPDATE/DELETE) - these are not tracked +- Always specify schemas explicitly: `public.users` instead of `users` + ## Troubleshooting +**Common errors** +- "permission denied": Remove `read_only=true` for write operations +- "relation does not exist": Use `list_tables` to verify table names and schemas +- "Not authenticated": Restart MCP connection and verify organization access +- Migration conflicts: Check `list_migrations` history before applying new migrations +**Using logs for debugging** +- Use `get_logs` to view service logs when certain action fails +- Available log types: `api`, `branch-action`, `postgres`, `edge-function`, `auth`, `storage`, `realtime` +- Check Postgres logs to see slow queries, errors, or connection issues +- Review API logs to debug PostgREST endpoint failures or RLS policy issues From 3c8c1b3724efe577f71b079b7cb864a1161f195b Mon Sep 17 00:00:00 2001 From: Jack Wotherspoon Date: Wed, 12 Nov 2025 08:48:35 -0500 Subject: [PATCH 3/7] chore: add Gemini CLI instructions to README --- README.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/README.md b/README.md index f5435103..dfaab38c 100644 --- a/README.md +++ b/README.md @@ -92,6 +92,32 @@ For more information, see the [VS Code MCP docs](https://code.visualstudio.com/d +
+Gemini CLI + +#### Install via command line: + +```bash +gemini mcp add -t http supabase https://mcp.supabase.com/mcp +``` + +#### Install using Supabase extension for Gemini CLI: + +The Supabase extension for Gemini CLI bundles the MCP server with a context +file and custom commands, teaching Gemini how to better use all tools. + +Use the following command to install the extension: + +```bash +gemini extensions install https://github.com/supabase-community/supabase-mcp +``` + +After adding the server or extension, start Gemini CLI and run `/mcp auth supabase` to authenticate. + +For more information, see the [Gemini CLI MCP docs](https://geminicli.com/docs/tools/mcp-server/). + +
+ ## Options The following options are configurable as URL query parameters: From e08430037e77274f6c2a3f3f899fe623538bc0c7 Mon Sep 17 00:00:00 2001 From: dshukertjr Date: Wed, 19 Nov 2025 23:06:18 +0900 Subject: [PATCH 4/7] remove readme changes --- README.md | 26 -------------------------- 1 file changed, 26 deletions(-) diff --git a/README.md b/README.md index dfaab38c..f5435103 100644 --- a/README.md +++ b/README.md @@ -92,32 +92,6 @@ For more information, see the [VS Code MCP docs](https://code.visualstudio.com/d -
-Gemini CLI - -#### Install via command line: - -```bash -gemini mcp add -t http supabase https://mcp.supabase.com/mcp -``` - -#### Install using Supabase extension for Gemini CLI: - -The Supabase extension for Gemini CLI bundles the MCP server with a context -file and custom commands, teaching Gemini how to better use all tools. - -Use the following command to install the extension: - -```bash -gemini extensions install https://github.com/supabase-community/supabase-mcp -``` - -After adding the server or extension, start Gemini CLI and run `/mcp auth supabase` to authenticate. - -For more information, see the [Gemini CLI MCP docs](https://geminicli.com/docs/tools/mcp-server/). - -
- ## Options The following options are configurable as URL query parameters: From f74e9dcc7699e9f0687107f8d55125965f76cd04 Mon Sep 17 00:00:00 2001 From: dshukertjr Date: Wed, 19 Nov 2025 23:07:17 +0900 Subject: [PATCH 5/7] remove query parameter settings from supabase.md --- SUPABASE.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/SUPABASE.md b/SUPABASE.md index 116108fe..1469dc7e 100644 --- a/SUPABASE.md +++ b/SUPABASE.md @@ -8,13 +8,6 @@ This extension allows you to access your Supabase projects and perform tasks lik ## Best Practices -**Security defaults** -- Use read-only mode (`?read_only=true`) to prevent accidental writes -- Scope to specific projects (`?project_ref=`) to limit access -- Limit tool access with feature groups (`?features=docs%2Caccount%2Cdatabase%2Cdebugging%2Cdevelopment`) - - Available groups: `account`, `docs`, `database`, `debugging`, `development`, `functions`, `storage`, `branching` -- Avoid connecting to production databases even in read-only mode - **Schema management** - Use `apply_migration` for schema changes (CREATE/ALTER/DROP tables) - these are tracked - Use `execute_sql` for queries and data operations (SELECT/INSERT/UPDATE/DELETE) - these are not tracked From 93d64a31fbb4478ec070e95ccb441b2e0bce2f5c Mon Sep 17 00:00:00 2001 From: Matt Rossman <22670878+mattrossman@users.noreply.github.com> Date: Tue, 9 Dec 2025 10:42:49 -0500 Subject: [PATCH 6/7] feat: align with Kiro steering Adapted from https://github.com/supabase-community/kiro-powers --- SUPABASE.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/SUPABASE.md b/SUPABASE.md index 1469dc7e..3b97b1e1 100644 --- a/SUPABASE.md +++ b/SUPABASE.md @@ -6,13 +6,32 @@ This extension allows you to access your Supabase projects and perform tasks lik **Key capabilities**: Execute SQL, manage migrations, deploy functions, generate TypeScript types, access logs, and search documentation. +Tools executing using this server affect the hosted Supabase project(s), and changes can be synced to the filesystem using Supabase CLI. Assume the hosted database is the source of truth for migration history, and use CLI to sync changes to the local workspace. + ## Best Practices +**Project identification** + +The user will likely have linked their Supabase CLI to a development project. You can find the linked project ref in `supabase/.temp/project-ref`, use this as the `project_id` in MCP tool calls. + **Schema management** + +To update tables: + +1. Call MCP `list_tables` to inspect the current schema +2. Call `apply_migration` with desired changes +3. Call MCP `get_advisors` to find and fix "security" and "performance" issues as needed with further migrations +4. Sync new migration(s) to `supabase/migrations/` locally with `supabase migration fetch --yes` +5. Generate updated types and review codebase to align usage + - Use `apply_migration` for schema changes (CREATE/ALTER/DROP tables) - these are tracked - Use `execute_sql` for queries and data operations (SELECT/INSERT/UPDATE/DELETE) - these are not tracked - Always specify schemas explicitly: `public.users` instead of `users` +**Type generation** + +While iterating on the schema, you should generate updated types with `supabase gen types --linked`. This outputs to stdio, so use `>` to redirect to a file. + ## Troubleshooting **Common errors** @@ -20,9 +39,16 @@ This extension allows you to access your Supabase projects and perform tasks lik - "relation does not exist": Use `list_tables` to verify table names and schemas - "Not authenticated": Restart MCP connection and verify organization access - Migration conflicts: Check `list_migrations` history before applying new migrations +- Frontend error `Could not find the '' column of '' in the schema cache`: Update types + implementation to ensure code matches current schema +- No project ref: Run `supabase link` to link the workspace to a hosted development project +- Data not appearing in app: Run `supabase db diff --linked`. If schema drift exists run `supabase db pull --yes` to store changes in a new local migration and repair remote migration history. Then proceed to update types and usage. **Using logs for debugging** - Use `get_logs` to view service logs when certain action fails - Available log types: `api`, `branch-action`, `postgres`, `edge-function`, `auth`, `storage`, `realtime` - Check Postgres logs to see slow queries, errors, or connection issues - Review API logs to debug PostgREST endpoint failures or RLS policy issues + +**Further resources** +- For MCP configuration help: https://supabase.com/mcp +- For Supabase CLI troubleshooting: https://supabase.com/docs/guides/cli/getting-started From afcd6d0833164311b16e0fad6b9ed908de4a13ad Mon Sep 17 00:00:00 2001 From: Matt Rossman <22670878+mattrossman@users.noreply.github.com> Date: Tue, 9 Dec 2025 10:55:52 -0500 Subject: [PATCH 7/7] feat: adapt CLI invocation instructions from Kiro Gemini wasn't understanding how to invoke with package manage prefix --- SUPABASE.md | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/SUPABASE.md b/SUPABASE.md index 3b97b1e1..21766955 100644 --- a/SUPABASE.md +++ b/SUPABASE.md @@ -8,6 +8,26 @@ This extension allows you to access your Supabase projects and perform tasks lik Tools executing using this server affect the hosted Supabase project(s), and changes can be synced to the filesystem using Supabase CLI. Assume the hosted database is the source of truth for migration history, and use CLI to sync changes to the local workspace. +## CLI invocation + +Supabase CLI may be installed globally (e.g. with homebrew or scoop) or as a project dependency (e.g. in "devDependency" with npm, pnpm, bun, etc.). Prefer using it as a project dependency to keep CLI version pinned in your development environment. + +**Package manager setup** + +To install or use CLI through a Node.js package manager, you must determine which package manager is desired for the project. + +You MUST either: + +- Determine the project's existing package manager by checking for popular lockfile formats (e.g. package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb) +- Ask the user which package manager they prefer + +For Node.js package managers, `supabase` commands MUST be prefixed with the package manager's command runner. +- npm: `npx supabase ...` +- pnpm: `pnpm supabase ...` +- bun: `bun supabase ...` + +**IMPORTANT** Every time a bare `supabase` command is mentioned, consider which prefix is needed and add it accordingly. + ## Best Practices **Project identification** @@ -21,7 +41,7 @@ To update tables: 1. Call MCP `list_tables` to inspect the current schema 2. Call `apply_migration` with desired changes 3. Call MCP `get_advisors` to find and fix "security" and "performance" issues as needed with further migrations -4. Sync new migration(s) to `supabase/migrations/` locally with `supabase migration fetch --yes` +4. Sync new migration(s) to `supabase/migrations/` locally with `[prefix?] supabase migration fetch --yes` 5. Generate updated types and review codebase to align usage - Use `apply_migration` for schema changes (CREATE/ALTER/DROP tables) - these are tracked @@ -30,7 +50,7 @@ To update tables: **Type generation** -While iterating on the schema, you should generate updated types with `supabase gen types --linked`. This outputs to stdio, so use `>` to redirect to a file. +While iterating on the schema, you should generate updated types with `[prefix?] supabase gen types --linked`. This outputs to stdio, so use `>` to redirect to a file. ## Troubleshooting @@ -40,8 +60,8 @@ While iterating on the schema, you should generate updated types with `supabase - "Not authenticated": Restart MCP connection and verify organization access - Migration conflicts: Check `list_migrations` history before applying new migrations - Frontend error `Could not find the '' column of '
' in the schema cache`: Update types + implementation to ensure code matches current schema -- No project ref: Run `supabase link` to link the workspace to a hosted development project -- Data not appearing in app: Run `supabase db diff --linked`. If schema drift exists run `supabase db pull --yes` to store changes in a new local migration and repair remote migration history. Then proceed to update types and usage. +- No project ref: Run `[prefix?] supabase link` to link the workspace to a hosted development project +- Data not appearing in app: Run `[prefix?] supabase db diff --linked`. If schema drift exists run `[prefix?] supabase db pull --yes` to store changes in a new local migration and repair remote migration history. Then proceed to update types and usage. **Using logs for debugging** - Use `get_logs` to view service logs when certain action fails