Supabase MCP Service Endpoint

  

Empower Cursor & Windsurf to orchestrate your Supabase infrastructure and run SQL statements with guaranteed security.

An advanced MCP service implementation providing safe access for Cursor and Windsurf to interact with Supabase data environments. Capabilities include comprehensive database administration functions, secure SQL execution routing, and access to the Supabase Management API, all enforced by robust security layers.

Index

Initialization • Capabilities • Debugging Help • Future Plans

✨ Core Features

• 💻 Protocol adherence: Works seamlessly with Cursor, Windsurf, Cline, and any MCP client supporting the stdio protocol.
• 🔐 Granular control over SQL operation mutability (read-only vs. read-write).
• 🔄 Resilient transaction management supporting both direct and connection-pooled links.
• 💻 Management capabilities for Supabase projects via the official Management API.
• 🧑‍💻 Administration of user accounts using Supabase Auth Admin interfaces exposed through the Python SDK.
• 🔨 Auxiliary utilities designed to optimize MCP client interaction workflows.
• 📦 Effortless deployment using standard Python package managers (uv, pipx, etc.).

Initialization

Prerequisites for System Setup

Installation mandates the presence of: - Python interpreter version 3.12 or newer. - PostgreSQL server, version 16 or higher.

Ensure that the uv package installer is available on your system if you opt for its use.

PostgreSQL Dependency Installation

⚠️ Crucial Note: PostgreSQL must be functional BEFORE attempting dependency installation, as psycopg2 compilation requires its development headers.

MacOS

brew install postgresql@16

Windows - Obtain and install PostgreSQL 16+ from https://www.postgresql.org/download/windows/ - Verify selection of "PostgreSQL Server" and "Command Line Tools" during setup

Phase 1. Service Installation

Since release v0.2.0, package installation is the primary method. Utilize your preferred Python package manager:

# Recommended method if pipx is present
pipx install supabase-mcp-server

# Alternative using uv
uv pip install supabase-mcp-server

pipx is favored for isolating package environments.

Alternatively, clone the repository and execute uv pip install -editable . from the root to install manually.

⚠️ Compilation failures related to psycopg2 typically indicate missing PostgreSQL development libraries (refer to the prerequisite section).

Source Code Installation

For local testing or development:

uv venv
# On Unix-like systems
source .venv/bin/activate
# On Windows (Command Prompt)
.venv\Scripts\activate
# Install package in editable mode
uv pip install -e .

Smithery.ai Integration

For automated deployment via Smithery, report any encountered issues as I have not yet verified this integration path.

To deploy Supabase MCP Service for Claude Desktop automatically:

npx -y @smithery/cli install @alexander-zuev/supabase-mcp --client claude

Phase 2. Connection Parameterization

Once the package is installed, configure your database access credentials. The service natively handles connections to both local and remote Supabase deployments.

Local Supabase Endpoint (Default)

The service defaults to connecting to a locally running Supabase instance using these standard parameters: - Host: 127.0.0.1:54322 - Password: postgres

💡 If you haven't altered these defaults and target the local environment, no environment variables are necessary.

Remote Supabase Deployment

⚠️ CRITICAL WARNING: Connection pooling mechanisms are currently unsupported and there are no immediate plans to integrate them. Kindly submit a use case if pooling is essential for your MCP server interaction.

Remote connections require defining: - SUPABASE_PROJECT_REF - The unique identifier from your project URL - SUPABASE_DB_PASSWORD - The database credential string - SUPABASE_REGION - (Optional) Defaults to us-east-1 - SUPABASE_ACCESS_TOKEN - (Optional) Required for Management API operations

Your SUPABASE_PROJECT_REF is extractable from the dashboard URL: - https://supabase.com/dashboard/project/<supabase-project-ref>

The server supports all global Supabase geographical zones: - us-west-1 - West US (North California) - us-east-1 - East US (North Virginia) - default - us-east-2 - East US (Ohio) - ca-central-1 - Canada (Central) - eu-west-1 - Western Europe (Ireland) - eu-west-2 - Western Europe (London) - eu-west-3 - Western Europe (Paris) - eu-central-1 - Central Europe (Frankfurt) - eu-central-2 - Central Europe (Zurich) - eu-north-1 - Northern Europe (Stockholm) - ap-south-1 - South Asia (Mumbai) - ap-southeast-1 - Southeast Asia (Singapore) - ap-northeast-1 - Northeast Asia (Tokyo) - ap-northeast-2 - Northeast Asia (Seoul) - ap-southeast-2 - Oceania (Sydney) - sa-east-1 - South America (São Paulo)

Configuration methods vary between Cursor and Windsurf clients. Consult the client-specific documentation below.

Cursor Integration

Cursor (since v0.46) allows two configuration pathways: - Project-level setup: Utilize a .cursor/mcp.json file alongside a .env file in your repository root for connection parameters. - Global setup: Define the server within Cursor Settings and use a globally stored .env file, which this service supports exclusively.

You can establish project-specific service definitions by: - Creating or updating .cursor/mcp.json within your repository structure.

⚠ Environment Variables Requirement: When using project-specific configuration (mcp.json), you must still supply connection settings via a .env file for the service to pick them up. I have not yet managed to get mcp.json to source environment variables directly.

{
    "mcpServers": {
      "filesystem": {
        "command": "supabase-mcp-server",
      }
    }
  }

For global configuration (independent of project structure), update a centralized .env file accessible via these commands:

# Create config directory and navigate (macOS/Linux)
mkdir -p ~/.config/supabase-mcp
cd ~/.config/supabase-mcp

# On Windows (PowerShell)
mkdir -Force "$env:APPDATA\supabase-mcp"
cd "$env:APPDATA\supabase-mcp"

Create and populate the .env file:

# macOS/Linux
nano ~/.config/supabase-mcp/.env

# Windows (PowerShell)
note "$env:APPDATA\supabase-mcp\.env"

Paste the required variables into the editor:

SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_DB_PASSWORD=your-db-password
SUPABASE_REGION=us-east-1  # Optional, defaults to us-east-1
SUPABASE_ACCESS_TOKEN=your-access-token  # Optional, for Management API access

Confirm the file's contents:

# macOS/Linux
cat ~/.config/supabase-mcp/.env

# Windows (PowerShell)
Get-Content "$env:APPDATA\supabase-mcp\.env"

Global configuration file locations: - Windows: %APPDATA%/supabase-mcp/.env - macOS/Linux: ~/.config/supabase-mcp/.env

Windsurf Integration

Windsurf utilizes the conventional .json format for defining MCP endpoints. Configure the server within mcp_config.json:

{
    "mcpServers": {
      "supabase": {
        "command": "/Users/username/.local/bin/supabase-mcp-server",  // Adjust path as necessary
        "env": {
          "SUPABASE_PROJECT_REF": "your-project-ref",
          "SUPABASE_DB_PASSWORD": "your-db-password",
          "SUPABASE_REGION": "us-east-1",  // Optional
          "SUPABASE_ACCESS_TOKEN": "your-access-token"  // Optional
        }
      }
    }
}

💡 Executable Path Discovery: - macOS/Linux: Execute which supabase-mcp-server - Windows: Execute where supabase-mcp-server

Parameter Precedence

The server prioritizes configuration in this sequence (highest priority first): 1. Direct Environment Variables 2. Local .env file (in the execution context) 3. Global configuration file: - Windows: %APPDATA%/supabase-mcp/.env - macOS/Linux: ~/.config/supabase-mcp/.env 4. Built-in defaults (local connection parameters)

Phase 3. Activating the Service in Clients

Any client adhering to the stdio protocol should function (e.g., Cline), though testing has been confined primarily to Cursor and Windsurf.

Cursor Activation

Navigate to Settings -> Features -> MCP Servers and append a new entry with:

# Use this name as desired
name: supabase
type: command
# If installed via pipx:
command: supabase-mcp-server
# If installed via uv:
command: uv run supabase-mcp-server

Success is indicated by a green status light and a counter showing the number of available tools.

Windsurf Activation

Access Cascade -> Click the wrench icon -> Configure -> Populate the configuration structure:

{
    "mcpServers": {
      "supabase": {
        "command": "/Users/username/.local/bin/supabase-mcp-server",  // Update this path
        "env": {
          "SUPABASE_PROJECT_REF": "your-project-ref",
          "SUPABASE_DB_PASSWORD": "your-db-password",
          "SUPABASE_REGION": "us-east-1",  // Optional
          "SUPABASE_ACCESS_TOKEN": "your-access-token"  // Optional
        }
      }
    }
}

If setup is correct, a green indicator will appear, and the service will be selectable in the available server list.

Debugging Help

Troubleshooting guidance: - Installation Check: Execute supabase-mcp-server standalone in your terminal. Failures here point to installation integrity issues. - MCP Service Configuration: If the standalone execution succeeds, the issue lies with the IDE's ability to locate or invoke the command. Ensure the provided command path is accurate. - Environment Variables Check: Verify that credentials are set either within mcp_config.json or in the global file (~/.config/supabase-mcp/.env or %APPDATA%\supabase-mcp\.env). - Accessing Logs: The service logs operational details, configuration status, and execution outcomes to a dedicated file: - Log Path: - macOS/Linux: ~/.local/share/supabase-mcp/mcp_server.log - Windows: %USERPROFILE%\.local\share\supabase-mcp\mcp_server.log - Viewing logs: ```bash # macOS/Linux cat ~/.local/share/supabase-mcp/mcp_server.log

# Windows (PowerShell)
Get-Content "$env:USERPROFILE\.local\share\supabase-mcp\mcp_server.log"
```

If these steps do not resolve the problem or if instructions seem outdated, please initiate a new issue report.

MCP Inspector Utility

For deep diagnostics, the MCP Inspector tool is invaluable. If installed from source, execute supabase-mcp-inspector within the repository directory to launch a localized inspection instance. This, combined with the server logs, provides complete visibility into service operations.

📝 Note: Direct execution of supabase-mcp-inspector after installation via package manager may exhibit suboptimal behavior; this will be rectified in the forthcoming release.

Capabilities Overview

Data Manipulation & Query Tools

Starting from version v0.3.0, the service fully supports operations spanning read and write contexts:

• Data Retrieval: Execution of SELECT statements for data extraction.
• DML Operations: Handling of INSERT, UPDATE, and DELETE for data modification.
• DDL Operations: Support for schema construction/modification/destruction (CREATE, ALTER, DROP).*

*DDL Execution Mandates: 1. Activation of read-write context via the live_dangerously mechanism. 2. Appropriate database role privileges.

Transaction Handling Strategies

Write operations can be performed using two methods:

1. Explicit Control (Recommended): sql BEGIN; CREATE TABLE public.test_table (id SERIAL PRIMARY KEY, name TEXT); COMMIT;

2. Single Command Execution: sql CREATE TABLE public.test_table (id SERIAL PRIMARY KEY, name TEXT);

For DDL routines, the tool descriptions guide Cursor/Windsurf clients to wrap operations in explicit transaction blocks (BEGIN/COMMIT).

Connection Modalities

This gateway employs different connection strategies based on the target: - Direct Link: Used when interfacing with a local Supabase setup. - Pooled Link: Used for remote Supabase connections via the Transaction Pooler.

Complex transaction sequences might encounter issues when utilizing the pooled connection model. For schema modifications in pooled environments, utilize explicit transaction blocks or the official dashboard SQL Editor.

Available Database Toolset: - get_db_schemas - Inventory of all schemas alongside their storage footprint and object counts. - get_tables - Catalog of tables within a schema, detailing size, row count, and structural metadata. - get_table_schema - Detailed structural blueprint of a table (columns, keys, relations). - execute_sql_query - Executes arbitrary PostgreSQL commands, fully supporting: - All query paradigms (SELECT, DML, DDL, etc.). - Transaction directives (BEGIN, COMMIT, ROLLBACK).

• Operational Modes:
• read-only - Default; permits only retrieval operations.
• read-write - All SQL statements allowed upon explicit activation.
• Safeguards:
• Initiates in read-only state.
• Requires explicit opt-in for write permissions.
• Automatically reverts to read-only state post-write execution.
• Intelligent state management to avert transactional errors.
• Future implementation: Comprehensive SQL query semantic analysis [TODO].

Management API Interface Tools

Since v0.3.0, the service can route arbitrary requests to the Supabase Management API, automatically handling project context injection and safety enforcement: - Included methods: - send_management_api_request: For sending custom requests to the Management API, with automatic credential and safety context application. - get_management_api_spec: Fetches the enhanced API specification, including safety annotations. - get_management_api_safety_rules: Retrieves all defined safety constraints (blocked/unsafe) with explanatory text. - live_dangerously: Toggles the operational security level. - Security Framework: - Operations are categorized as safe, unsafe, or blocked based on risk assessment. - Dynamic switching between safe and unsafe modes is supported. - High-impact operations (e.g., project deletion) are unconditionally blocked.

Auth Administration Tools

Initially, I considered mirroring the entire Python SDK. However, recognizing the frequent need for rapid test user creation, I prioritized exposing the Auth Admin SDK methods. This eliminates manual, error-prone SQL scripting for user management. Refer to the Auth Admin SDK documentation for full capabilities.

Release v0.3.6 introduced direct access to Supabase Auth Admin endpoints via the Python SDK: - Included methods: - get_auth_admin_methods_spec: Retrieves the documentation map for all accessible Auth Admin functions. - call_auth_admin_method: Invokes Auth Admin functions directly with correct parameter mapping. - Supported Functions: - get_user_by_id: Fetch user record via unique ID. - list_users: Paginated retrieval of user records. - create_user: Provision a new system user. - delete_user: Erase a user record by ID. - invite_user_by_email: Dispatch an invitation URL. - generate_link: Create authentication links (e.g., magic link). - update_user_by_id: Modify existing user attributes. - delete_factor: Remove a user's multi-factor authentication component (Note: Currently unimplemented in the underlying SDK).

Rationale: SDK vs. Raw SQL for Auth Management

Using the dedicated Auth Admin SDK offers significant benefits over manipulating auth.* schema tables directly: - Feature Parity: Enables features impossible via SQL alone (e.g., sending invites, managing MFA). - Reliability: Guarantees correct execution compared to handcrafted SQL on sensitive auth tables. - Usability: Provides clear, validated methods.

• Output Structure:
  • Methods yield structured Python objects, not simple key-value mappings.
  • Attributes are accessed via dot notation (e.g., result.user.id).
• Caveats and Constraints:
  • UUID Format: Many calls necessitate valid UUIDs for IDs, resulting in explicit validation failures if incorrect.
  • Email Service: Functions like invite_user_by_email require proper SMTP configuration within your Supabase project.
  • Link Context: Link generation differs: signup creates a user, while magiclink/recovery require pre-existence.
  • Error Reporting: Errors reflect the Supabase API's detailed response, which may not perfectly mirror dashboard messaging.
  • SDK Gaps: Certain API functions, such as delete_factor, are present in the API but may lag in SDK implementation.

Future Plans

• Package Manager Install Simplification - ✅ (v0.2.0)
• Multi-Region Supabase Connectivity Support - ✅ (v0.2.2)
• Programmatic Supabase Management API Access with Security Layers - ✅ (v0.3.0)
• Read/Write SQL Operations with Safety Guards - ✅ (v0.3.0)
• Enhanced Transactional Integrity for all Connection Types - ✅ (v0.3.2)
• Full Exposure of Native Python SDK Constructs - ✅ (v0.3.6)
• Rigorous Validation for SQL Query Classification (Write vs. Read)
• Evaluation of DDL Query Versioning Strategies (?)
• Development of Utilities for Log Access (Database, Edge Functions) (?)
• Integration with Supabase Command Line Interface (?)

Log Streaming Integration Research

I plan to investigate the feasibility of establishing a connection to Supabase's database log streams for enhanced debugging capabilities (assuming current support is absent or insufficient.)

---

Farewell! ☺️

WIKIPEDIA: XMLHttpRequest (XHR) represents an API implemented as a JavaScript object, whose methods facilitate the dispatching of HTTP requests from a web browser to a designated web server. These methods enable browser-based applications to communicate with the server subsequent to the initial page load, allowing for asynchronous data exchange. XMLHttpRequest is a foundational element of Ajax programming. Before Ajax, the standard means of server interaction involved full page refreshes via hyperlinks or form submissions.

== Historical Context == The foundational concept for XMLHttpRequest was introduced in 2000 by the development team behind Microsoft Outlook. This concept was subsequently integrated into Internet Explorer 5 (released in 1999). Critically, the initial implementation did not employ the XMLHttpRequest identifier; instead, developers utilized ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). By the release of Internet Explorer 7 (2006), universal support for the standard XMLHttpRequest identifier was established across all major browser engines, including Mozilla's Gecko (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) published the initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. A subsequent Level 2 specification was published by the W3C as a Working Draft on February 25, 2008. Level 2 introduced features for monitoring request progress events, enabling cross-site transfers, and handling raw byte streams. By the close of 2011, the Level 2 specifications were merged back into the primary document. Development oversight was transitioned to WHATWG at the end of 2012, which now maintains a living standard defined using Web IDL.

== Implementation Details == The standard procedure for dispatching a server request using XMLHttpRequest involves several programmatic stages:

1. Object Instantiation: Create an instance of the XMLHttpRequest object via its constructor.
2. Request Definition: Invoke the "open" method to specify the HTTP method, target resource URI, and determine whether the operation will be synchronous or asynchronous.
3. Asynchronous Listener Setup: For asynchronous modes, register an event handler function to react to state transitions of the request.
4. Request Initiation: Trigger the process by calling the "send" method. Data payload, if any, is passed to this method.
5. Response Handling: Monitor state changes via the registered listener. Upon completion (state 4, the "done" state), the server's response body is typically accessible via the "responseText" property.

Beyond these core steps, XMLHttpRequest provides extensive control over request behavior. Custom HTTP headers can be injected to modify server expectations. Data can be uploaded efficiently in the send call. Responses can be parsed directly from JSON into usable JavaScript structures, or processed incrementally as data arrives, avoiding wait times for the full transfer. Furthermore, requests can be terminated early or subjected to time-out constraints.