Supabase Integration Agent for MCP

This server functions as a Model Context Protocol (MCP) bridge, enabling interaction with Supabase backends. Its primary capabilities include executing detailed data retrieval operations and deriving precise TypeScript data structures from the underlying database schema.

Core Capabilities

• Data Retrieval Execution: Perform complex SQL interactions against any table, supporting:
• Explicit schema declaration
• Column projection limitations
• Conditional filtering via multiple logical operators
• Offset/limit based pagination

• Robust operational feedback mechanism

• Type Schema Synthesis: Automatically derive TypeScript definitions for database entities:

• Compatibility across all defined schemas (e.g., public, auth, storage)
• Operational parity for locally run or externally hosted Supabase environments
• Direct streaming of generated types to the console interface
• Automated discovery of necessary project configuration references

Prerequisites for Deployment

1. Runtime Environment: Node.js (version 16 or superior is mandatory)
2. Target System: An accessible Supabase project (local deployment or remote service)
3. CLI Dependency: The official Supabase command-line utility (essential for type derivation)

Deployment Procedure

1. Obtain Repository Source Code: bash git clone https://github.com/yourusername/supabase-mcp-server.git cd supabase-mcp-server

2. Install Required Dependencies: bash npm install

3. Install Supabase CLI (a dependency for schema tooling): bash

Via npm package manager

npm install -g supabase

Alternative for macOS users via Homebrew

brew install supabase/tap/supabase

Configuration Steps

1. Acquire Supabase Access Credentials:

2. Remote Services:

   1. Access the project dashboard settings.
   2. Navigate to the API configuration section.
   3. Secure the Project URL and the service_role authorization token (the anon key is insufficient).

3. Local Instances:

   1. Ensure the local Supabase stack is operational.
   2. Utilize the default local endpoint (commonly http://localhost:54321).
   3. Use the local service_role credential set.

4. Establish Environment Variables: bash

Create and populate the .env file (ensuring it is git-ignored)

echo "SUPABASE_URL=your_project_url SUPABASE_KEY=your_service_role_key" > .env

1. Compile the Server Artifacts: bash npm run build

Integration Protocols

Integration with Claude Desktop Environment

1. Access Claude Desktop Configuration File:
2. macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
3. Windows: %APPDATA%\Claude\claude_desktop_config.json

4. Linux: ~/.config/Claude/claude_desktop_config.json

5. Inject the Server Definition:

{ "mcpServers": { "supabase": { "command": "node", "args": ["/absolute/path/to/supabase-mcp-server/build/index.js"], "env": { "SUPABASE_URL": "your_project_url", "SUPABASE_KEY": "your_service_role_key" } } } }

Integration with VSCode Extension (Claude Dev)

1. Locate VSCode Settings File:
2. macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
3. Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

4. Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

5. Apply the Configuration (Structure mirrors the Claude Desktop schema).

Operational Examples

Executing a Data Fetch Operation

typescript // Example: Retrieving specific fields from 'users' table with a boolean filter supabase query_table { "schema": "public", "table": "users", "select": "id,name,email", "where": [ { "column": "is_active", "operator": "eq", "value": true } ] }

Deriving TypeScript Definitions

typescript // Example: Generating types for the primary database schema supabase generate_types { "schema": "public" }

Available Service Functions

query_table

Retrieves records from a designated table, supporting schema scope and detailed filtering.

Parameters: - schema (Optional): The database schema namespace; defaults to 'public'. - table (Mandatory): The precise name of the data collection to query. - select (Optional): A comma-delimited string specifying columns for projection. - where (Optional): An array defining filtering criteria, each element requiring: - column: The field identifier. - operator: Must be one of: eq, neq, gt, gte, lt, lte, like, ilike, is. - value: The target comparison data point.

generate_types

Initiates the process of synthesizing TypeScript interfaces based on the database structure.

Parameters: - schema (Optional): The schema to analyze; defaults to 'public'.

Troubleshooting Diagnostics

Issues Related to Type Generation Failures

1. CLI Verification: Ensure the Supabase utility is callable: bash supabase --version

2. Local Project Validation:

3. Confirm the Supabase local services are actively running.

4. Cross-reference the configured service_role key for accuracy.

5. Hosted Project Verification:

6. Validate that the extracted project reference identifier is correct.
7. Confirm that the supplied credentials utilize the elevated service_role scope.

Anomalies During Data Retrieval

1. Verify Schema/Table Naming Conventions.
2. Validate column names within both projection (select) and filtering (where) definitions.
3. Confirm that the service_role possesses adequate read permissions on the target objects.

Contribution Guidelines

1. Fork the primary repository.
2. Establish a feature branch: git checkout -b feature/new-enhancement
3. Commit relevant modifications: git commit -am 'Feat: Implemented [X]'
4. Push the branch to the origin remote: git push origin feature/new-enhancement
5. Submit a formal Pull Request for review.

Licensing

This project operates under the terms of the MIT License (refer to the LICENSE file).

WIKIPEDIA: Cloud computing is defined by ISO as "a paradigm for enabling network access to a scalable and elastic pool of shareable physical or virtual resources with self-service provisioning and administration on-demand." It is often colloquially termed "the cloud."

== Key Attributes == The National Institute of Standards and Technology (NIST) formalized five indispensable traits for cloud infrastructures in 2011. These definitions are authoritative:

On-demand self-service: "A consumer can unilaterally provision computing capabilities, such as server time and network storage, as needed automatically without requiring human interaction with each service provider." Broad network access: "Capabilities are available over the network and accessed through standard mechanisms that promote use by heterogeneous thin or thick client platforms (e.g., mobile phones, tablets, laptops, and workstations)." Resource pooling: " The provider's computing resources are pooled to serve multiple consumers using a multi-tenant model, with different physical and virtual resources dynamically assigned and reassigned according to consumer demand." Rapid elasticity: "Capabilities can be elastically provisioned and released, in some cases automatically, to scale rapidly outward and inward commensurate with demand. To the consumer, the capabilities available for provisioning often appear unlimited and can be appropriated in any quantity at any time." Measured service: "Cloud systems automatically control and optimize resource use by leveraging a metering capability at some level of abstraction appropriate to the type of service (e.g., storage, processing, bandwidth, and active user accounts). Resource usage can be monitored, controlled, and reported, providing transparency for both the provider and consumer of the utilized service." ISO has since updated and expanded these criteria as of 2023.

== Historical Context ==

The conceptual foundation of cloud computing traces back to the 1960s with the maturation of time-sharing systems facilitated by remote job entry (RJE). During this period, the operational model centered on data centers, where users submitted tasks to specialized operators managing mainframe systems. The focus was heavily on experimentation to maximize the accessibility of high-capacity computational resources through time-sharing, optimizing infrastructure, platform layers, applications, and overall end-user efficiency. The adoption of the 'cloud' graphical abstraction for virtualized services surfaced in 1994, utilized by General Magic to denote the accessible domain for agents operating within their Telescript environment. This visual metaphor is largely attributed to David Hoffman, a communications strategist at General Magic, who based it on established conventions within telecommunications and networking. The term 'cloud computing' gained mainstream traction in 1996 following a business strategy document drafted by Compaq Computer Corporation outlining their vision for future internet and computing capabilities.