Labsco
alexander-zuev logo

Supabase

★ 827

from alexander-zuev

Manage your Supabase project, execute SQL queries, and more.

🔥🔥🔥✓ VerifiedPaid serviceAdvanced setup
#email#automation#analytics#database#cloud#git#search#maps

Query | MCP server for Supabase

🌅 More than 17k installs via pypi and close to 30k downloads on Smithery.ai — in short, this was fun! 🥳 Thanks to everyone who has been using this server for the past few months, and I hope it was useful for you. Since Supabase has released their own official MCP server, I've decided to no longer actively maintain this one. The official MCP server is as feature-rich, and many more features will be added in the future. Check it out!

Query MCP is an open-source MCP server that lets your IDE safely run SQL, manage schema changes, call the Supabase Management API, and use Auth Admin SDK — all with built-in safety controls.

Table of contents

Getting started • Feature overview • Troubleshooting • Changelog

✨ Key features

  • 💻 Compatible with Cursor, Windsurf, Cline and other MCP clients supporting stdio protocol

  • 🔐 Control read-only and read-write modes of SQL query execution

  • 🔍 Runtime SQL query validation with risk level assessment

  • 🛡️ Three-tier safety system for SQL operations: safe, write, and destructive

  • 🔄 Robust transaction handling for both direct and pooled database connections

  • 📝 Automatic versioning of database schema changes

  • 💻 Manage your Supabase projects with Supabase Management API

  • 🧑‍💻 Manage users with Supabase Auth Admin methods via Python SDK

  • 🔨 Pre-built tools to help Cursor & Windsurf work with MCP more effectively

  • 📦 Dead-simple install & setup via package manager (uv, pipx, etc.)

Feature Overview

Database query tools

Since v0.3+ server provides comprehensive database management capabilities with built-in safety controls:

SQL Query Execution: Execute PostgreSQL queries with risk assessment

  • Three-tier safety system:

  • safe: Read-only operations (SELECT) - always allowed

  • write: Data modifications (INSERT, UPDATE, DELETE) - require unsafe mode

  • destructive: Schema changes (DROP, CREATE) - require unsafe mode + confirmation

SQL Parsing and Validation:

  • Uses PostgreSQL's parser (pglast) for accurate analysis and provides clear feedback on safety requirements

Automatic Migration Versioning:

  • Database-altering operations operations are automatically versioned

  • Generates descriptive names based on operation type and target

Safety Controls:

  • Default SAFE mode allows only read-only operations

  • All statements run in transaction mode via asyncpg

  • 2-step confirmation for high-risk operations

Available Tools:

  • get_schemas: Lists schemas with sizes and table counts

  • get_tables: Lists tables, foreign tables, and views with metadata

  • get_table_schema: Gets detailed table structure (columns, keys, relationships)

  • execute_postgresql: Executes SQL statements against your database

  • confirm_destructive_operation: Executes high-risk operations after confirmation

  • retrieve_migrations: Gets migrations with filtering and pagination options

  • live_dangerously: Toggles between safe and unsafe modes

Management API tools

Since v0.3.0 server provides secure access to the Supabase Management API with built-in safety controls:

Available Tools:

  • send_management_api_request: Sends arbitrary requests to Supabase Management API with auto-injection of project ref

  • get_management_api_spec: Gets the enriched API specification with safety information

  • Supports multiple query modes: by domain, by specific path/method, or all paths

  • Includes risk assessment information for each endpoint

  • Provides detailed parameter requirements and response formats

  • Helps LLMs understand the full capabilities of the Supabase Management API

  • get_management_api_safety_rules: Gets all safety rules with human-readable explanations

  • live_dangerously: Toggles between safe and unsafe operation modes

Safety Controls:

  • Uses the same safety manager as database operations for consistent risk management

  • Operations categorized by risk level:

  • safe: Read-only operations (GET) - always allowed

  • unsafe: State-changing operations (POST, PUT, PATCH, DELETE) - require unsafe mode

  • blocked: Destructive operations (delete project, etc.) - never allowed

  • Default safe mode prevents accidental state changes

  • Path-based pattern matching for precise safety rules

Note: Management API tools only work with remote Supabase instances and are not compatible with local Supabase development setups.

Auth Admin tools

I was planning to add support for Python SDK methods to the MCP server. Upon consideration I decided to only add support for Auth admin methods as I often found myself manually creating test users which was prone to errors and time consuming. Now I can just ask Cursor to create a test user and it will be done seamlessly. Check out the full Auth Admin SDK method docs to know what it can do.

Since v0.3.6 server supports direct access to Supabase Auth Admin methods via Python SDK:

  • Includes the following tools:

  • get_auth_admin_methods_spec to retrieve documentation for all available Auth Admin methods

  • call_auth_admin_method to directly invoke Auth Admin methods with proper parameter handling

  • Supported methods:

  • get_user_by_id: Retrieve a user by their ID

  • list_users: List all users with pagination

  • create_user: Create a new user

  • delete_user: Delete a user by their ID

  • invite_user_by_email: Send an invite link to a user's email

  • generate_link: Generate an email link for various authentication purposes

  • update_user_by_id: Update user attributes by ID

  • delete_factor: Delete a factor on a user (currently not implemented in SDK)

Why use Auth Admin SDK instead of raw SQL queries?

The Auth Admin SDK provides several key advantages over direct SQL manipulation:

Functionality: Enables operations not possible with SQL alone (invites, magic links, MFA)

Accuracy: More reliable then creating and executing raw SQL queries on auth schemas

Simplicity: Offers clear methods with proper validation and error handling

  • Response format:

  • All methods return structured Python objects instead of raw dictionaries

  • Object attributes can be accessed using dot notation (e.g., user.id instead of user["id"])

  • Edge cases and limitations:

  • UUID validation: Many methods require valid UUID format for user IDs and will return specific validation errors

  • Email configuration: Methods like invite_user_by_email and generate_link require email sending to be configured in your Supabase project

  • Link types: When generating links, different link types have different requirements:

  • signup links don't require the user to exist

  • magiclink and recovery links require the user to already exist in the system

  • Error handling: The server provides detailed error messages from the Supabase API, which may differ from the dashboard interface

  • Method availability: Some methods like delete_factor are exposed in the API but not fully implemented in the SDK

Logs & Analytics

The server provides access to Supabase logs and analytics data, making it easier to monitor and troubleshoot your applications:

Available Tool: retrieve_logs - Access logs from any Supabase service

Log Collections:

  • postgres: Database server logs

  • api_gateway: API gateway requests

  • auth: Authentication events

  • postgrest: RESTful API service logs

  • pooler: Connection pooling logs

  • storage: Object storage operations

  • realtime: WebSocket subscription logs

  • edge_functions: Serverless function executions

  • cron: Scheduled job logs

  • pgbouncer: Connection pooler logs

Features: Filter by time, search text, apply field filters, or use custom SQL queries

Simplifies debugging across your Supabase stack without switching between interfaces or writing complex queries.

Automatic Versioning of Database Changes

"With great power comes great responsibility." While execute_postgresql tool coupled with aptly named live_dangerously tool provide a powerful and simple way to manage your Supabase database, it also means that dropping a table or modifying one is one chat message away. In order to reduce the risk of irreversible changes, since v0.3.8 the server supports:

  • automatic creation of migration scripts for all write & destructive sql operations executed on the database

  • improved safety mode of query execution, in which all queries are categorized in:

  • safe type: always allowed. Includes all read-only ops.

  • writetype: requires write mode to be enabled by the user.

  • destructive type: requires write mode to be enabled by the user AND a 2-step confirmation of query execution for clients that do not execute tools automatically.

Universal Safety Mode

Since v0.3.8 Safety Mode has been standardized across all services (database, API, SDK) using a universal safety manager. This provides consistent risk management and a unified interface for controlling safety settings across the entire MCP server.

All operations (SQL queries, API requests, SDK methods) are categorized into risk levels:

  • Low risk: Read-only operations that don't modify data or structure (SELECT queries, GET API requests)

  • Medium risk: Write operations that modify data but not structure (INSERT/UPDATE/DELETE, most POST/PUT API requests)

  • High risk: Destructive operations that modify database structure or could cause data loss (DROP/TRUNCATE, DELETE API endpoints)

  • Extreme risk: Operations with severe consequences that are blocked entirely (deleting projects)

Safety controls are applied based on risk level:

  • Low risk operations are always allowed

  • Medium risk operations require unsafe mode to be enabled

  • High risk operations require unsafe mode AND explicit confirmation

  • Extreme risk operations are never allowed

How confirmation flow works

Any high-risk operations (be it a postgresql or api request) will be blocked even in unsafe mode.

You will have to confirm and approve every high-risk operation explicitly in order for it to be executed.

Changelog

  • 📦 Simplified installation via package manager - ✅ (v0.2.0)

  • 🌎 Support for different Supabase regions - ✅ (v0.2.2)

  • 🎮 Programmatic access to Supabase management API with safety controls - ✅ (v0.3.0)

  • 👷‍♂️ Read and read-write database SQL queries with safety controls - ✅ (v0.3.0)

  • 🔄 Robust transaction handling for both direct and pooled connections - ✅ (v0.3.2)

  • 🐍 Support methods and objects available in native Python SDK - ✅ (v0.3.6)

  • 🔍 Stronger SQL query validation ✅ (v0.3.8)

  • 📝 Automatic versioning of database changes ✅ (v0.3.8)

  • 📖 Radically improved knowledge and tools of api spec ✅ (v0.3.8)

  • ✍️ Improved consistency of migration-related tools for a more organized database vcs ✅ (v0.3.10)

  • 🥳 Query MCP is released (v0.4.0)

For a more detailed roadmap, please see this discussion on GitHub.

Star History

Enjoy! ☺️