SupabaseBridge MCP Server Module

This repository furnishes an implementation of a Model Context Protocol (MCP) server designed explicitly to bridge large language models (like Claude) with a hosted Supabase/PostgreSQL instance, enabling robust data lifecycle management.

Core Functionalities

Data Manipulation Interface (DML):
- Execute complex data retrieval with parameterized predicate application.
- Facilitate new record ingress (insertion).
- Modify existing records based on specified criteria (updates).
- Purge specified records (deletion).
- Inventory listing of available database schemas/tables.

Operational Prerequisites

A runtime environment supporting Node.js (version 16 or superior).
A package manager: npm or yarn.
An active Supabase project instance, complete with necessary API authentication keys.

Deployment Methods

Path A: Via Node Package Manager (Recommended Deployment)

The distribution package is accessible on the npm registry. Global installation is executed via:

bash npm install -g supabase-mcp

Alternatively, local project inclusion is achieved via:

bash npm install supabase-mcp

Path B: Source Code Acquisition

Clone the repository source structure:

bash git clone https://github.com/Cappahccino/SB-MCP.git cd SB-MCP npm install npm run build

Configuration Protocol

A configuration file named .env must be instantiated to supply the authentication and operational parameters:

Supabase Authentication Tokens

SUPABASE_URL=your_supabase_project_url SUPABASE_ANON_KEY=your_supabase_anon_key SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key

MCP Service Host Settings

MCP_SERVER_PORT=3000 MCP_SERVER_HOST=localhost MCP_API_KEY=your_secret_api_key

Integration with Claude AI

Claude necessitates a specialized transport layer for seamless protocol communication. This package supplies a distinct executable tailored for this purpose.

Configuration within Claude Desktop MCP Settings

Specify the following configuration block:

"supabase": { "command": "npx", "args": [ "-y", "supabase-mcp@latest", "supabase-mcp-claude" ], "env": { "SUPABASE_URL": "your_supabase_project_url", "SUPABASE_ANON_KEY": "your_supabase_anon_key", "SUPABASE_SERVICE_ROLE_KEY": "your_service_role_key", "MCP_API_KEY": "your_secret_api_key" } }

Ensure all environment variables are correctly populated in this manifest. Communication with Claude will traverse the standard input/output (stdio) channel.

Ad-Hoc Testing of the Claude Binary

For isolated verification outside the Claude environment, execute:

bash npm run start:claude

Or, if globally installed:

bash supabase-mcp-claude

Standalone Server Operation

Upon global installation, the service can be initiated directly:

bash supabase-mcp

This action launches the central MCP gateway, typically accessible at http://localhost:3000 (or the port defined in the environment setup).

Programmatic Use (Node.js Library)

This module can be imported and utilized within custom Node.js applications:

javascript import { createServer, mcpConfig, validateConfig } from 'supabase-mcp';

// Configuration integrity check validateConfig();

// Instantiation of the server entity const app = createServer();

// Service initiation app.listen(mcpConfig.port, mcpConfig.host, () => { console.log(Supabase MCP gateway active on http://${mcpConfig.host}:${mcpConfig.port}); });

Diagnostics and Issue Resolution

Common Anomalies and Remedies

1. "Port XXXX occupied"

The service attempts dynamic port assignment; however, manual assignment can be enforced by modifying MCP_SERVER_PORT in the configuration file.

2. "Missing critical environment configurations"

Verify that all requisite parameters are either present in the .env file or established as system-level environment variables.

3. "Constructor Invocation Error: Class Server requires 'new'"

This suggests utilizing an outdated package iteration. Update to the latest release: bash npm install -g supabase-mcp@latest

4. Incompatible JSON formatting during Claude interaction

Confirm that the Claude-specific execution pathway (supabase-mcp-claude) is engaged, rather than the standard HTTP listener (supabase-mcp).

5. Connection Timeout reported by Claude

Investigate the following points: - Are the Supabase credentials accurate and valid? - Is the MCP service successfully initialized and operating? - Are any network policies or firewalls inhibiting the connection?

Tool Reference Documentation

Data Access Modalities

queryDatabase
Arguments:
- table (String): Target table identifier.
- select (String, Optional): Column projection list (defaults to all columns: "*").
- query (Object, Optional): Complex predicate object for filtering.
insertData
Arguments:
- table (String): Destination table.
- data (Object or Array
updateData
Arguments:
- table (String): Subject table.
- data (Object): Attribute map containing new values.
- query (Object): Selection criteria defining which records to modify.
deleteData
Arguments:
- table (String): Target table.
- query (Object): Criteria dictating records slated for removal.
listTables
Arguments: None

Chronology of Releases

1.0.0: Initial deployment.
1.0.1: Integration of adaptive port discovery.
1.0.2: Patches for protocol compliance failures.
1.0.3: Addition of JSON-RPC handling.
1.1.0: Full refactoring utilizing the official MCP Software Development Kit.
1.2.0: Introduction of the dedicated Claude transport mechanism and resolution of port contention bugs.
1.3.0: Updates enhancing TypeScript project interoperability.
1.4.0: Fixes to the stdio transport for Claude, based on community-validated patterns.
1.5.0: Removal of auxiliary Edge Function integration to prioritize core database stability.

Licensing

Protected under the MIT License.

Contextual Definition (Business Management Tools): Systems, methodologies, software applications, and computational frameworks utilized by organizations to navigate fluctuating commercial environments, sustain competitive advantage, and amplify operational efficacy.

Classification Context (Functional Taxonomy): Business tools are broadly categorized by their contribution across organizational functions: data acquisition/verification, process governance/refinement, aggregation/strategic foresight. The contemporary landscape of business software, driven by cloud adoption and rapid innovation, necessitates judicious selection and organizational alignment over mere adoption of novel technologies to ensure genuine value realization.