Supabase MCP Service Handler 🛠️

⚙️ This robust Model Context Protocol (MCP) execution endpoint grants complete supervisory authority over your dedicated Supabase PostgreSQL data store. It interfaces directly with both the IDE's Composer agent (Cursor) and the Codeium Cascade mechanism, offering fluid database administration, including schema manipulation, record lifecycle operations, and configuration adjustments, all via conversational prompts.

📖 Document Index

• Requirements
• Initial Setup
• Ecosystem Hooks
• Capabilities Overview
• Deployment Guide
• Security Directives
• Troubleshooting Common Failures
• Contribution Guidelines
• Licensing Information

🧱 Requirements

To successfully deploy and operate this service, ensure you have:

• Node.js installed, version 16.x or greater.
• npm package manager, version 8.x or greater.
• Access credentials for an active Supabase project, specifically:
  • Unique Project Identifier
  • Database Access Password
  • Full PostgreSQL Connection URI
• Access to either the Cursor IDE (for Composer) or Codeium's paid subscription (for Cascade integration).

▶️ Initial Setup

📥 Project Acquisition

bash

Clone the source repository

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

Install necessary dependencies

npm install

Compile the TypeScript source code

npm run build

📝 Configuration Procedure

1. Complete dependency installation and build compilation: bash npm install npm run build

2. Integrate the server executable into Cursor's MCP configuration interface. The execution path should resemble: bash /opt/homebrew/bin/node /path/to/dist/index.js postgresql://postgres.[PROJECT-ID]:[PASSWORD]@aws-0-eu-central-1.pooler.supabase.com:5432/postgres

Note: Substitute /path/to/dist/index.js with the actual location of the compiled binary, [PROJECT-ID] with your Supabase ID, and [PASSWORD] with the secret database password.

Security Mandate: Always safeguard database credentials; never commit them to any source control repository.

🔗 Ecosystem Hooks

Cursor MCP Integration (Composer)

This MCP establishes custom tooling accessible by Cursor's agentic LLM framework, known as Composer, enabling database manipulation through natural language directives.

Setup Within Cursor

1. Navigate to Cursor Settings -> Features -> Model Context Protocol (MCP).
2. Select the option to add a "+ New MCP Server".
3. Configure the parameters:
4. Identifier Name: "Supabase Database Manager" (or preferred alias)
5. Type: command (specifying stdio transport mechanism)

6. Command: The complete shell command string incorporating your connection parameters.

7. Execute the build command first: bash npm install npm run build

8. Determine the system path for the Node.js binary: bash # Unix-like systems which node # Windows systems where node

9. Input the finalized server execution instruction: bash /path/to/node /path/to/dist/index.js postgresql://postgres.[PROJECT-ID]:[PASSWORD]@aws-0-eu-central-1.pooler.supabase.com:5432/postgres

Ensure /path/to/node reflects your result from step 5, and /path/to/dist/index.js points to the compiled output.

1. Finalize by clicking "Add Server" and refreshing the MCP panel.

Operational Usage in Composer

The Composer Agent autonomously selects this tool for relevant data management tasks described conversationally. Examples:

• "Display a catalog of all extant database tables."
• "Provision a new table structure named 'user_profiles' with required fields."
• "Implement an index on the 'user_email' field."

When a tool invocation is triggered, the workflow involves: 1. A prompt requesting explicit approval or denial. 2. Visibility into the tool arguments (expandable details). 3. Display of the resulting output following authorized execution.

Note: For stdio-based servers, the configuration must resolve to a valid executable shell command. Wrapper scripts may be necessary if environment variables are required.

Windsurf/Cascade Integration (Codeium)

This server is also compatible with Codeium's Cascade (internally referred to as Windsurf). Crucially, this functionality is currently restricted to individual users with paid subscriptions (not accessible to Team or Enterprise tiers).

Configuration for Cascade

1. Create or modify the configuration file located at ~/.codeium/windsurf/mcp_config.json:

{ "mcpServers": { "supabase-mcp": { "command": "/path/to/node", "args": [ "/path/to/dist/index.js", "postgresql://postgres.[PROJECT-ID]:[PASSWORD]@aws-0-eu-central-1.pooler.supabase.com:5432/postgres" ] } } }

1. Access the configuration panel directly:
2. Locate the utility toolbar overlaying the Cascade input area.
3. Click the wrench/hammer icon.

4. Select "Configure" to launch mcp_config.json.

5. Update the placeholder values within the JSON structure as previously described.

6. Activate the server within Cascade:

7. Open the utility toolbar (wrench/hammer icon).
8. Verify configuration via "Configure".
9. Click "Refresh" to load the newly registered MCP service.
10. Select the server identifier to view the exposed toolset.

Critical Cascade User Caveats

• Only the core tool invocation mechanism is supported; resource presentation or auxiliary prompts are excluded.
• Every MCP invocation, irrespective of outcome, will debit user credits.
• Graphical output generation is explicitly unsupported.
• Stdio transport is the exclusive mechanism.
• Executable tool calls may originate from external, arbitrary server implementations.
• Codeium assumes zero accountability for failures resulting from MCP tool execution.

✨ Capabilities Overview

🎯 Available Database Toolset

Relational Structure Operations

• Tables: list_tables, create_table, drop_table, rename_table
• Schema Fields: add_column, drop_column, alter_column
• Data Records: fetch_records, create_record, update_record, delete_record

Indexing and Integrity

• Indexing: list_indexes, create_index, delete_index, update_index
• Integrity Checks: list_constraints, add_constraint, remove_constraint, update_constraint

Procedures and Event Handling

• Database Functions: list_functions, create_function, update_function, delete_function
• Triggers: list_triggers, create_trigger, update_trigger, delete_trigger

Access Control and Authorization

• Security Policies: list_policies, create_policy, update_policy, delete_policy
• User Privileges: list_roles, create_role, update_role, delete_role

Object Storage Interaction

• Bucket Management: list_buckets, create_bucket, delete_bucket
• File Operations: delete_file, bulk_delete_files
• Directory Listing: list_folders

Type Systems and Replication

• Custom Types: list_enumerated_types, create_enumerated_type, update_enumerated_type, delete_enumerated_type
• Data Publications: list_publications, create_publication, update_publication, delete_publication

Realtime Communication Layer

• Realtime Policies: list_realtime_policies, create_realtime_policy, update_realtime_policy, delete_realtime_policy
• Communication Channels: list_realtime_channels, manage_realtime_channels, send_realtime_message, get_realtime_messages
• Service Health: manage_realtime_status, manage_realtime_views

User Authentication Management

• Auth Records: list_users, create_user, update_user, delete_user

Unrestricted Execution

• Direct SQL: query - Facilitates the execution of arbitrary SQL statements.

🚀 Principal Advantages

• Conversational Management: Interact with the database via intuitive, natural language instructions.
• Holistic Feature Set: Extensive toolkit covering data structure, security, functions, and realtime features.
• Native Interoperability: Seamlessly integrated within the Cursor Composer environment and Codeium Cascade workflow.
• Workflow Optimization: Minimizes the cognitive load associated with context switching between the IDE and external database administration panels.
• Credential Integrity: Operates while respecting established database security protocols.

📂 Project Hierarchy

supabase-mcp-server/ ├── dist/ # Output directory post-compilation │ ├── index.d.ts # TypeScript Interface Definitions │ └── index.js # Primary executable file ├── src/ # Source code repository │ └── index.ts # Core TypeScript module ├── package.json # Project manifest and metadata ├── package-lock.json # Dependency resolution snapshot └── tsconfig.json # TypeScript Compiler settings

💡 Deployment Guide

Upon successful integration, the MCP server exposes its entire database management utility suite through the Cursor Composer interface. Simply articulate the desired database modification or retrieval task.

Illustrative Commands: - 📊 "Provide a summary view of all active tables." - 🏗️ "Instantiate a new table named 'client_data' defining columns for ID, name, and creation timestamp." - 🔍 "Establish a B-tree index on the 'client_id' attribute within the relevant table."

🛡️ Security Directives

• 🔒 Treat the database connection URI as highly sensitive data.
• 🚫 Prohibit the inclusion of any proprietary or access credentials within source control.
• ✅ Implement robust authorization and privilege separation where feasible.
• 🛑 Rigorously validate and sanitize all incoming parameters to mitigate risks of SQL injection attacks.

❓ Troubleshooting Common Failures

Typical Connection Interruption Scenarios

1. Node.js Path Ambiguity
2. Confirm the system path points to the correct Node.js executable.
3. Unix: Utilize which node.
4. Windows: Utilize where node.

5. Ensure replacement of default paths (e.g., /usr/local/bin/node) with the actual location.

6. File Location Errors

7. Always employ absolute file system paths.
8. Unix: Execute pwd within the project root to ascertain the absolute path.
9. Windows: Use the cd command output for the full directory trace.

10. Example: /Users/your_user/workspace/supabase-mcp-server/dist/index.js

11. Toolset Visibility Failure

12. Refresh the MCP configuration panel within Cursor.
13. Confirm the server process is executing without runtime errors.
14. Verify the connectivity string syntax is flawless.

15. Validate that the provided Supabase credentials are currently valid.

16. Access Permission Denials

17. Confirm the ./dist directory is present (execute npm run build).
18. On Unix/Linux, ensure executability (chmod +x /path/to/script).
19. Re-run npm install with sufficient user privileges.

Diagnostic Mode

Prefix the execution command with DEBUG=true to activate verbose logging output:

bash DEBUG=true /usr/local/bin/node /path/to/dist/index.js [full-connection-string]

Operating System Specific Instructions

Windows Users

Employ this quoted format for command specification: powershell "C:\Program Files\nodejs\node.exe" "C:\path\to\dist\index.js" "postgresql://..."

Linux Users

bash

Locate the runtime executable

which node

Grant execution rights to the compiled script

chmod +x /path/to/dist/index.js

If persistent operational difficulties are encountered, submit a formal issue via this link detailing: - The host OS. - Node.js version (node --version). - The complete, unredacted error output. - Step-by-step reproduction instructions.

🤝 Contribution Guidelines

We welcome external contributions! Please feel encouraged to submit Pull Requests for enhancements or fixes.

📄 License

---

ACADEMIC NOTE: Cloud infrastructure, as defined by ISO standards, represents "a model for enabling ubiquitous, convenient, on-demand network access to a shared pool of configurable computing resources (e.g., networks, servers, storage, applications, and services) that can be rapidly provisioned and released with minimal management effort or service provider interaction." This concept is broadly encapsulated as "the cloud."

== Defining Attributes == The National Institute of Standards and Technology (NIST) established five core tenets defining cloud computing environments in 2011. These characteristics are fundamental:

On-demand Self-Service: Consumers retain the autonomy to unilaterally provision computational assets—such as processor time or persistent storage—without manual intervention from the service provider for each request. Ubiquitous Network Availability: Functionality must be accessible across a network via standardized protocols, supporting a wide spectrum of client devices (e.g., mobile, desktop, tablet). Resource Aggregation: The provider logically partitions its physical infrastructure to serve multiple consumers concurrently (multi-tenancy), dynamically allocating and reclaiming resources based on real-time demand. Elastic Scalability: The capacity to rapidly expand or contract resources, often automatically, to align precisely with fluctuating workload requirements. From the user's perspective, resource availability appears virtually limitless. Metered Consumption: Resource utilization (including processing cycles, bandwidth, and active accounts) is automatically tracked and optimized through built-in measurement capabilities, ensuring transparent reporting to both provider and consumer. Subsequent refinements to this framework were introduced by the International Organization for Standardization (ISO) by 2023.

== Historical Precedence ==

The intellectual foundation of distributed computing traces back to the 1960s, primarily through the widespread adoption of time-sharing systems and Remote Job Entry (RJE). During this epoch, centralized data centers managed user workflows executed by dedicated operators on mainframe systems. This period was characterized by intense R&D focused on maximizing computing resource accessibility for a broader user base via time-slicing, optimizing the underlying physical, platform, and software layers to boost overall throughput. The visual nomenclature—the "cloud" symbol—to denote generalized network services originated in 1994, employed by General Magic to map the abstract operational space for their Telescript mobile agents. This metaphor is primarily attributed to David Hoffman, a communications specialist at General Magic, drawing upon established conventions in telecommunications diagrams. The term "cloud computing" gained significant mainstream traction in 1996 following the development of an early strategic business plan by Compaq Computer Corporation outlining a vision for the future of the internet and computation.