# coleam00/supabase-mcp architecture

> Architecture diagram of the GitHub repository coleam00/supabase-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/coleam00/supabase-mcp
- Repository: https://github.com/coleam00/supabase-mcp

## Overview

##### Project type and purpose
- This is a lightweight microservice (MCP server) packaged as a Docker container.
- Purpose: Expose CRUD tools (read, create, update, delete) over the Model Context Protocol (MCP) so that AI assistants can perform operations against a Supabase database through a standardized stdio interface.

##### File structure
- Top level:
- Dockerfile – builds the container image “mcp/supabase.”
- example_mcp_config.json – shows how an AI assistant configures this server.
- requirements.txt – Python dependencies.
- supabase_mcp/ – Python package containing:
– server.py (main entry point implementing the MCP interface)
– tests/ (unit tests for server logic)
- Supporting docs (README, PLANNING.md, TASKS.md) aid development but are outside the runtime path.

##### README for additional insights
- Confirms the server listens on stdio, implements the MCP spec, and expects environment variables SUPABASE_URL and SUPABASE_SERVICE_KEY.
- Describes the four tools (read_table_rows, create_table_records, update_table_records, delete_table_records).
- Shows workflow: AI assistant ⟷ MCP server (stdio) ⟷ Supabase REST/JS SDK ⟷ Supabase database.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External AI Assistant
    A["AI Assistant Client"]:::external

    %% Docker Engine Boundary
    subgraph "Docker Engine"
        direction TB
        subgraph "MCP Server Container"
            direction TB
            S["MCP Server\n(supabase_mcp/server.py)"]:::service
            EV["Environment Variables\nSUPABASE_URL & SERVICE_KEY"]:::config
        end
    end

    %% Supabase Database
    DB["Supabase Database"]:::external

    %% Development Artifacts
    subgraph "Development Artifacts"
        direction TB
        CF1["example_mcp_config.json"]:::config
        CF2["requirements.txt"]:::config
        DOC1["README.md"]:::config
        DOC2["PLANNING.md"]:::config
        DOC3["TASKS.md"]:::config
        DOC4["LICENSE"]:::config
        subgraph "supabase_mcp Package"
            direction TB
            INIT["__init__.py"]:::service
            SF["server.py"]:::service
            subgraph tests
                direction TB
                TD["tests"]:::tests
                TF["test_server.py"]:::tests
            end
        end
    end

    %% Data Flows
    A -->|"JSON-RPC over stdio"| S
    S -->|"HTTP REST/SDK Calls"| DB
    DB -->|"Responses"| S
    S -->|"RPC Responses over stdio"| A

    %% Configuration Flow
    CF1 --> S
    EV --> S
    CF2 --> S

    %% Click Events
    click S "https://github.com/coleam00/supabase-mcp/blob/main/supabase_mcp/server.py"
    click SF "https://github.com/coleam00/supabase-mcp/blob/main/supabase_mcp/server.py"
    click INIT "https://github.com/coleam00/supabase-mcp/blob/main/supabase_mcp/__init__.py"
    click TD "https://github.com/coleam00/supabase-mcp/tree/main/supabase_mcp/tests"
    click TF "https://github.com/coleam00/supabase-mcp/blob/main/supabase_mcp/tests/test_server.py"
    click CF1 "https://github.com/coleam00/supabase-mcp/blob/main/example_mcp_config.json"
    click CF2 "https://github.com/coleam00/supabase-mcp/blob/main/requirements.txt"
    click DOC1 "https://github.com/coleam00/supabase-mcp/blob/main/README.md"
    click DOC2 "https://github.com/coleam00/supabase-mcp/blob/main/PLANNING.md"
    click DOC3 "https://github.com/coleam00/supabase-mcp/blob/main/TASKS.md"
    click DOC4 "https://github.com/coleam00/supabase-mcp/tree/main/LICENSE"
    click Dockerfile "https://github.com/coleam00/supabase-mcp/tree/main/Dockerfile"

    %% Styles
    classDef external fill:#9cf,stroke:#069;
    classDef service fill:#9f9,stroke:#080;
    classDef config fill:#ccc,stroke:#999;
    classDef tests fill:#ddd,stroke:#666;
```
