Supabase Query MCP Server

DatabasesPython

End-to-end management of Supabase via chat interface

Available Tools

execute_sql

Execute SQL queries against your Supabase database with validation and safety controls

get_logs

Retrieve logs from multiple Supabase services with filtering and search capabilities

manage_schema

Create and modify database schema with automatic migration versioning

call_management_api

Access the Supabase Management API to manage projects, organizations, and settings

use_auth_admin

Manage authentication and users through the Auth Admin SDK

introspect_database

Explore database structure, tables, and relationships

Query MCP is an open-source server that enables comprehensive management of Supabase databases through a chat interface. It allows you to safely execute SQL queries, manage schema changes, call the Supabase Management API, and utilize the Auth Admin SDK with built-in safety controls. The server provides powerful features like automatic migration versioning, access to logs across multiple Supabase services, and database introspection tools.

Overview

Query MCP provides a powerful interface for managing your Supabase projects through natural language. It enables you to execute SQL queries, manage database schemas, interact with the Supabase Management API, and leverage the Auth Admin SDK—all with built-in safety controls.

Installation

Prerequisites

Python 3.12 or higher
A Supabase project with API credentials

Installation Options

Option 1: Install via PyPI

pip install supabase-mcp-server

Option 2: Install with uv (recommended)

uv install supabase-mcp-server

Configuration

Create a .env file in your project directory based on the .env.example file from the repository.
Configure the following essential environment variables:
- SUPABASE_URL: Your Supabase project URL
- SUPABASE_KEY: Your Supabase service role key (for database operations)
- SUPABASE_ACCESS_TOKEN: Your Supabase access token (for management API)
- SUPABASE_PROJECT_ID: Your Supabase project ID
Optional configuration:
- SUPABASE_REGION: Your Supabase project region (e.g., us-east-1)
- SUPABASE_ORG_ID: Your Supabase organization ID
- PORT: Port for the MCP server (default: 8000)

Usage

Starting the Server

Run the MCP server using:

supabase-mcp-server

Or with uv:

uv run supabase-mcp-server

Connecting to the Server

Add the following configuration to your MCP client (Claude, Cursor, etc.):

"mcpServers": {
  "supabase-query": {
    "command": "supabase-mcp-server",
    "args": []
  }
}

If using uv:

"mcpServers": {
  "supabase-query": {
    "command": "uv",
    "args": [
      "run",
      "supabase-mcp-server"
    ]
  }
}

Docker Support

The repository includes a Dockerfile for containerized deployment:

docker build -t supabase-mcp-server .
docker run -p 8000:8000 --env-file .env supabase-mcp-server

Features

SQL Query Execution: Safely run SQL queries against your Supabase database
Schema Management: Create, modify, and track database schema changes
Migration Versioning: Automatically version your database migrations
Management API Integration: Access the full Supabase Management API
Auth Admin SDK: Manage authentication and users
Log Retrieval: Access logs from multiple Supabase services
Database Introspection: Explore your database structure

Security Considerations

The server requires service role keys with high privileges
Consider running the server in a secure environment
Review SQL queries before execution, especially for production databases
Use environment variables for sensitive credentials, never hardcode them

Troubleshooting

Ensure your Supabase credentials are correct
Check that your environment variables are properly set
Verify network connectivity to Supabase services
Review server logs for detailed error messages

For more information, visit thequery.dev or check the GitHub repository.