Supabase MCP Server

A Model Context Protocol (MCP) server for interacting with Supabase databases. This server implements the Model Context Protocol using the FastMCP Python SDK to provide database operation tools for large language models (LLMs).

Features

• Read records from Supabase tables with filtering, pagination, and sorting
• Create new records (single or batch) in Supabase tables
• Update existing records based on filter conditions
• Delete records from tables based on filter conditions
• Communicates using MCP’s Stdio transport

Prerequisites

• Python 3.8 or higher
• A Supabase project with tables already set up
• Supabase service role key for authentication

Installation

1. Clone this repository:

   git clone https://github.com/gevans3000/supabase-mcp.git
   cd supabase-mcp
   

2. Set up a virtual environment (recommended):

   # Create a virtual environment
   python -m venv venv
   
   # Activate the virtual environment
   # On Windows:
   venvScriptsactivate
   # On macOS/Linux:
   source venv/bin/activate
   

3. Install the dependencies:

   pip install -r requirements.txt
   

4. Set up environment variables:

   • Copy the .env.example file to .env:

     cp .env.example .env
     # On Windows, use:
     # copy .env.example .env
     

   • Fill in your Supabase URL and service role key in the .env file:

     SUPABASE_URL=your_supabase_project_url
     SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
     

Usage

Starting the Server

Make sure your virtual environment is activated, then run the server:

python server.py

The server uses Stdio transport, so it will listen for MCP requests on standard input and respond on standard output.

Integrating with MCP Clients

This server implements the Model Context Protocol and can be integrated with any MCP-compatible client. For example, you can use it with LLM frameworks that support MCP tools.

Adding to Windsurf/Cursor MCP Configuration

To add this MCP server to your Windsurf or Cursor configuration:

1. Locate your mcp_config.json file:

   • Windows: C:Users<username>.codeiumwindsurfmcp_config.json
   • macOS: ~/.codeium/windsurf/mcp_config.json
   • Linux: ~/.codeium/windsurf/mcp_config.json

2. Add the Supabase MCP server to the mcpServers section:

{
  "mcpServers": {
    // ... other servers
    "supabase": {
      "command": "python",
      "args": [
        "/path/to/your/supabase-mcp/server.py"
      ],
      "env": {
        "SUPABASE_URL": "your_supabase_url",
        "SUPABASE_SERVICE_ROLE_KEY": "your_supabase_key"
      }
    }
  }
}

Replace /path/to/your/supabase-mcp/server.py with the absolute path to your server.py file.

Note: For better isolation, you can use the Python executable from your virtual environment:

{
  "mcpServers": {
    "supabase": {
      "command": "/path/to/your/venv/bin/python",  // or "venv\Scripts\python.exe" on Windows
      "args": [
        "/path/to/your/supabase-mcp/server.py"
      ]
    }
  }
}

3. Restart your Windsurf/Cursor application to apply the changes.

4. The Supabase MCP tools will now be available to your AI assistant.

Tool Descriptions

The server provides the following tools:

1. read_records

Reads records from a Supabase database table with flexible querying options.

Parameters:

• table (string, required): Name of the table to read from
• columns (string, optional, default: “*”): Columns to select (comma-separated or * for all)
• filters (object, optional): Filtering conditions as key-value pairs
• limit (integer, optional): Maximum number of records to return
• offset (integer, optional): Number of records to skip for pagination
• order_by (object, optional): Sorting options as column:direction pairs

Example:

{
  "table": "users",
  "columns": "id,name,email",
  "filters": {"is_active": true},
  "limit": 10,
  "offset": 0,
  "order_by": {"created_at": "desc"}
}

2. create_records

Creates one or more records in a Supabase database table.

Parameters:

• table (string, required): Name of the table to create records in
• records (object or array, required): A single record object or array of record objects to create

Example (single record):

{
  "table": "users",
  "records": {
    "name": "John Doe",
    "email": "john@example.com",
    "role": "user"
  }
}

Example (multiple records):

{
  "table": "users",
  "records": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "role": "user"
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "role": "admin"
    }
  ]
}

3. update_records

Updates existing records in a Supabase database table based on filter conditions.

Parameters:

• table (string, required): Name of the table to update records in
• updates (object, required): Fields to update as key-value pairs
• filters (object, required): Filtering conditions to identify records to update

Example:

{
  "table": "users",
  "updates": {
    "is_verified": true,
    "last_login_at": "2025-04-04T15:30:00Z"
  },
  "filters": {
    "id": 123
  }
}

4. delete_records

Deletes records from a Supabase database table based on filter conditions.

Parameters:

• table (string, required): Name of the table to delete records from
• filters (object, required): Filtering conditions to identify records to delete

Example:

{
  "table": "expired_sessions",
  "filters": {
    "expires_at": {"lt": "2025-01-01T00:00:00Z"}
  }
}

Development

Project Structure

• server.py: Main MCP server implementation
• supabase_client.py: Supabase client wrapper
• requirements.txt: Python dependencies
• .env.example: Example environment variables file

Adding New Tools

To add a new tool to the server:

1. Define a Pydantic model for the tool’s request parameters in server.py
2. Add a handler method to the SupabaseMCPServer class
3. Register the tool in the _register_tools method with a descriptive name and documentation

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.