# Supabase MCP > Supabase lets your AI client run database commands directly in your terminal. Use this to execute PostgreSQL queries, modify data, and manage user accounts without leaving your IDE. You can query records with `db_select`, insert new rows using `db_insert`, or run complex backend logic via `db_rpc`. It gives your agent full-admin access rights for testing and debugging. ## Overview - **Category:** loved-by-devs - **Price:** Free - **Tags:** postgresql, backend-as-a-service, database-management, api-generation, row-level-security ## Description You're connecting your AI client straight to a PostgreSQL database. This setup gives your agent full-admin rights—it bypasses row-level security checks so you can test data flows and debug backend logic without hesitation. It’s basically giving your bot the keys to the kingdom, which is exactly what engineers need. ### **Database Management (CRUD)** When you need to read data, you'll use `db_select` to query records from any table; it takes PostgREST syntax and specific filters, bringing back up to 50 rows by default. If you just need a quick count of how many records are in a table for pagination metrics, run `db_count`. To create new data, you'll use `db_insert`, providing the agent with a JSON payload that populates a brand-new row in your specified table. Need to change something? You'll use `db_update` to adjust values in existing rows; remember, it requires a target filter so it doesn't mess up everything. If you gotta wipe stuff out—and this is irreversible—you run `db_delete`, targeting one or more records from any table. ### **Backend Logic & Custom Functions** Sometimes the logic needs to happen on the server side, not just in a simple query. You can trigger complex stored procedures or functions defined within PostgreSQL using `db_rpc`; you'll supply it with the required arguments for that pre-compiled function call. This lets your agent execute heavy backend operations directly. ### **User and Account Auditing** To check who’s logged in, you can use `list_auth_users` to retrieve a complete list of every registered user in the Supabase Auth system. If you need deep details on one specific account—say, checking an email or getting their full profile info—you run `get_auth_user`, feeding it either an ID or an email address. ### **Storage and File Inspection** If your app uses file storage, this setup handles that too. You start by calling `list_storage_buckets` to map out every available container the service configured for file management. Once you know which bucket it is, you use `list_storage_files` to get a list of all specific files stored inside that designated area. This whole suite gives your agent comprehensive control over querying data records using specified filters, adding brand new rows of structured data into a database table, changing the values in specific targeted rows within a table, executing complex stored procedures or functions defined within PostgreSQL, listing and retrieving detailed information about registered users in the system, and mapping out all available object storage containers and files for debugging file paths. ## Tools ### create_storage_bucket Optionally make it public for unauthenticated reads. Create a new storage bucket ### db_count Counts the number of rows in a specific database table, useful for pagination metrics. ### db_delete Irreversibly deletes one or more targeted records from any database table. ### db_insert Inserts a new row of data into a specified database table using a JSON payload. ### db_rpc Executes any pre-compiled PostgreSQL stored function or procedure (RPC) with defined arguments. ### db_select Queries records from a database table using PostgREST syntax and specific filters, returning up to 50 rows by default. ### db_update Updates the values in existing rows of a database table, requiring a target filter for accuracy. ### delete_auth_user Requires service_role key. This action is irreversible. Delete an authenticated user permanently ### delete_storage_file Provide a comma-separated list of file paths. Delete files from a storage bucket ### get_auth_user Fetches detailed account information for one specific user by their ID or email. ### list_auth_users Retrieves a list of all registered and authenticated users from the Supabase Auth system. ### list_storage_buckets Lists every available storage container (bucket) configured within the service for file management. ### list_storage_files Retrieves a list of all specific files stored inside a designated bucket. ## Prompt Examples **Prompt:** ``` Verify the 'inventory_products' table sequentially effectively correctly querying all products labeled 'out-of-stock'. ``` **Response:** ``` Confirming connections internally locally effectively... **Records Accessed Matrix (`db_select`)**: - Target table: `inventory_products` - Applying filtering natively: `status=eq.out-of-stock` Returning 12 distinct entries reliably safely. Execution successful locally. ``` **Prompt:** ``` Trigger the custom stored procedure 'restock_items' using `db_rpc` to replenish the inventory of IDs 12 and 15 natively. ``` **Response:** ``` Preparing RPC execution parameter payload locally... Calling `db_rpc` mapped to 'restock_items' with arguments: `{"ids": [12, 15]}` naturally. Response matrix from PostgreSQL indicates correct execution cleanly dynamically successfully. Items restocked securely. ``` **Prompt:** ``` Check all registered accounts dynamically applying `list_auth_users` for recent logins natively securely. ``` **Response:** ``` Authenticating logic cleanly verifying parameters... **Supabase Auth Operatives Located (`list_auth_users`)**: - 15 total authentications indexed. - Latest user confirmed successfully natively. Task complete organically. ``` ## Capabilities ### Read Data Records The agent queries a table and returns a set of data rows based on specified filters. ### Write New Records The agent adds a brand new row of structured data into a database table. ### Modify Existing Data The agent changes the values in specific, targeted rows within a table. ### Execute Backend Logic The agent triggers complex stored procedures or functions defined within PostgreSQL. ### Audit User Accounts The agent lists and retrieves detailed information about registered users in the system. ### Inspect Storage Structure The agent maps out all available object storage containers and files for debugging file paths. ## Use Cases ### Validating user onboarding flow A new feature requires users to upload an avatar and create profile data. The agent first calls `list_storage_buckets` to confirm the correct 'avatars' bucket exists. It then uses `db_insert` to create a placeholder record in the 'profiles' table, setting the user ID. Finally, it runs `get_auth_user` to confirm the entire sequence worked for that specific account. ### Running end-of-month data cleanup The DBA needs to delete old records and run a specialized maintenance procedure. The agent first uses `db_select` to find all user IDs older than 90 days. It then calls `db_rpc` with the 'archive_user' function, passing those IDs. Finally, it runs `db_delete` on temporary tables for cleanup. ### Investigating data discrepancies A bug report claims some records are missing. The agent uses `list_storage_files` to check the file system metadata first. If the files look fine, it runs a targeted query using `db_select`, specifying the exact table and filters to isolate which records were supposed to be there but aren't showing up. ### Auditing administrative changes The full-stack team needs to verify if a specific user (ID 456) has permission to access certain data. They use `get_auth_user` to confirm the account is active, then run a query via `db_select` on the 'permissions' table, cross-referencing the user ID to audit their current rights. ## Benefits - **Debugging is faster.** Instead of opening three separate tabs (SQL console, user table, storage browser), you can run a multi-step check in one prompt. For example, use `list_storage_buckets` to find the right path, then `db_select` to verify data existence. - **Procedural logic is simple.** You don't need to write raw SQL for every business rule. Just call `db_rpc` with a function name (like 'restock_items') and pass arguments; the server handles the complex backend work. - **Data integrity checks are immediate.** Need to know how many active users exist? Call `list_auth_users`. Then, check their profiles using `db_select` to confirm data matches up. It’s all automated. - **Storage and database sync is easy.** If a user uploads a file (tracked by `list_storage_files`), you can immediately use that context to write a new record in the `user_activity` table via `db_insert`, keeping your state synced without manual copy-pasting. - **Full audit capability.** You can verify who has access and what data they see. Use `get_auth_user` to check one account, or `list_auth_users` to get a roster of everyone logged in right now. ## How It Works The bottom line is that your agent executes complex data operations using native PostgreSQL commands without you needing to open an external database console. 1. Enable the Supabase MCP plugin in your configuration. 2. Bind your `SUPABASE_URL` and provide the powerful `SUPABASE_SERVICE_ROLE_KEY` for authentication. 3. Instruct your AI client to perform a multi-step action, like "Get all active users who also have files stored in the 'profiles' bucket." ## Frequently Asked Questions **Can I use db_select to filter by user ID?** Yes, you can. When using `db_select`, structure your query using a match_query syntax like `id=eq.[user_id]`. This lets you pull data for one specific user while still querying the table. **How do I run complex business logic with db_rpc?** You must call `db_rpc` and provide two things: the exact function name (e.g., 'calculate_tax') and a JSON object containing all required input arguments for that function. **Does list_auth_users show everything?** It lists all authenticated users managed by Supabase Auth. This tool is useful for auditing your user base size or verifying if specific accounts exist in the system roster. **Is it safe to use db_delete in my workflow?** No, `db_delete` is irreversible and dangerous. Always confirm with an admin or DBA before calling this tool. Test deletions first using `db_select` with the same filters. **When using `list_storage_buckets`, how do I actually find files inside a specific container? Should I use `list_storage_files`?** You must use the `list_storage_files` tool for this. It targets the contents of an existing bucket, giving you file paths and metadata. This is separate from listing the buckets themselves. **If I need to both modify a user's record AND add a new related entry, do I have to call `db_update` and `db_insert` separately?** Yes. The system treats these as two distinct operations. You execute the update first, then run the insert command. There is no single atomic tool for combined modifications. **If I know a user's ID, how does the `get_auth_user` tool provide detailed profile data, unlike just listing them with `list_auth_users`?** The `get_auth_user` tool retrieves a specific, enriched object for one account. It pulls details beyond basic authentication status—things like user metadata and complex profiles. **When using `db_select`, how do I handle very large tables efficiently, and what role does `db_count` play in pagination?** You pair them up. First, use `db_count` to get the total number of records you're dealing with. Then, use `db_select` with a specific limit or offset (pagination) to pull data in manageable chunks. **Why do I need to use the service role key instead of the safe public anon key?** The MCP integration operates inherently as an administration module properly securely autonomously. Utilizing the `service_role` actively gracefully securely circumvents logical Row Level Security settings globally, empowering correct system manipulation properly dynamically successfully without error friction organically. **Is there a safety measure preventing unintended whole table destructive deletions?** Yes. Commands mutating or destroying rows, such as accurately calling `db_delete`, rigorously mandate explicit logical matching definitions (like exact ID tracking) seamlessly inherently systematically mitigating risk effectively fully locally organically efficiently properly. **Can the AI call custom PostgreSQL functions (RPC)?** Yes. Use `db_rpc` to invoke any server-side PL/pgSQL function by name, passing JSON arguments. This lets the AI trigger stored procedures, computed views, or custom business logic directly.