📌Overview

Purpose: The Supabase MCP Server provides complete administrative control over Supabase PostgreSQL databases, enabling users to efficiently manage their database operations via natural language commands.

Overview: This framework is built to connect seamlessly with Cursor's Composer and Codeium's Cascade, turning the complexities of database management into simple, conversational commands. It encompasses a wide variety of tools for handling tables, records, indices, and more, all while maintaining database security.

Key Features:

• Natural Language Control: Users can interact with the database using intuitive conversational commands to perform various operations effortlessly.

• Comprehensive Database Tools: Full suite of functionalities for managing tables, records, indices, functions, triggers, security policies, roles, and storage management.

• Seamless Integration: Designed to work directly within Cursor's Composer and Codeium's Cascade, enhancing productivity by minimizing context switching.

• Secure Access: Ensures database interactions maintain proper security through appropriate authentication and user access controls.

---

Supabase MCP Server 🚀

A powerful Model Context Protocol (MCP) server that provides full administrative control over your Supabase PostgreSQL database through both Cursor's Composer and Codeium's Cascade. This tool enables seamless database management with comprehensive features for table operations, record management, schema modifications, and more.

📚 Table of Contents

• Prerequisites
• Quick Start
• Integrations
• Features
• Usage
• Security Notes
• Troubleshooting
• Contributing
• License

🔧 Prerequisites

• Node.js >= 16.x
• npm >= 8.x
• A Supabase project with:
  • Project ID
  • Database password
  • PostgreSQL connection string
• Cursor IDE or Codeium's Cascade (for paying users)

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/Quegenx/supabase-mcp-server.git
cd supabase-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Configuration

1. Install dependencies and build the project:

   npm install
   npm run build
   

2. In Cursor's MCP settings, add the server with this command:

   /opt/homebrew/bin/node /path/to/dist/index.js postgresql://postgres.[PROJECT-ID]:[PASSWORD]@aws-0-eu-central-1.pooler.supabase.com:5432/postgres
   

   Replace:

   • /path/to/dist/index.js with your actual path
   • [PROJECT-ID] with your Supabase project ID
   • [PASSWORD] with your database password

Keep your database credentials secure and never commit them to version control.

🎯 Integrations

Cursor MCP Integration

The Model Context Protocol (MCP) allows you to provide custom tools to agentic LLMs in Cursor. This server can be integrated with Cursor's Composer feature, providing direct access to all database management tools through natural language commands.

Setting up in Cursor

1. Open Cursor Settings > Features > MCP

2. Click the "+ Add New MCP Server" button

3. Fill in the modal form:

   • Name: "Supabase MCP" (or any preferred nickname)
   • Type: command (stdio transport)
   • Command: Your full command string with connection details

4. Build the project first:

   npm install
   npm run build
   

5. Get your Node.js path:

   # On Mac/Linux
   which node
   # On Windows
   where node
   

6. Add the server command:

   /path/to/node /path/to/dist/index.js postgresql://postgres.[PROJECT-ID]:[PASSWORD]@aws-0-eu-central-1.pooler.supabase.com:5432/postgres
   

   Replace placeholders accordingly.

7. Click "Add Server" and then refresh.

Using the Tools in Cursor

The Composer Agent automatically detects and uses tools when you describe database tasks, such as:

• "List all tables in my database"
• "Create a new users table"
• "Add an index to the email column"

You will be prompted to approve tool calls.

For stdio servers, the command should be a valid shell command. Use a wrapper script if environment variables are needed.

Windsurf/Cascade Integration

This MCP server supports Codeium's Cascade (Windsurf) integration, available for paying individual users only.

Setting up with Cascade

1. Create or edit ~/.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"
         ]
       }
     }
   }
   

2. Replace placeholders:

   • /path/to/node with Node.js path
   • /path/to/dist/index.js with actual path
   • [PROJECT-ID] and [PASSWORD] accordingly

3. In Cascade, configure and refresh MCP servers via toolbar hammer icon.

Important Notes for Cascade Users

• Only tools functionality is supported (no prompts or resources)
• MCP tool calls consume credits regardless of success
• Image output is not supported
• Only stdio transport type is supported
• Tool calls can invoke arbitrary server code
• Cascade does not assume liability for failures

✨ Features

Available Database Tools

• Tables: list, create, drop, rename
• Columns: add, drop, alter
• Records: fetch, create, update, delete
• Indexes: list, create, delete, update
• Constraints: list, add, remove, update
• Functions: list, create, update, delete
• Triggers: list, create, update, delete
• Policies: list, create, update, delete
• Roles: list, create, update, delete
• Storage: list/create/delete buckets, delete files, list folders
• Enumerated Types: list, create, update, delete
• Publications: list, create, update, delete
• Realtime Features: policies, channels, messages, status, views
• User Management: list, create, update, delete users
• Direct SQL Access: execute custom queries

Key Benefits

• Natural language control over Supabase database
• Full suite of database management tools
• Seamless integration with Cursor and Cascade
• Developer friendly, reducing context switching
• Secure access with proper authentication

📁 Project Structure

supabase-mcp-server/
├── dist/                    # Compiled JavaScript files
│   ├── index.d.ts           # TypeScript declarations
│   └── index.js             # Main JavaScript file
├── src/                     # Source code
│   └── index.ts             # Main TypeScript file
├── package.json             # Project config
├── package-lock.json        # Dependency lock file
└── tsconfig.json            # TypeScript config

💡 Usage

Once configured, describe database tasks in Cursor's Composer and the AI will execute the appropriate commands. Examples:

• "Show me all tables in my database"
• "Create a new users table with id, name, and email columns"
• "Add an index on the email column of the users table"

🔒 Security Notes

• Keep your database connection string secure
• Never commit sensitive credentials to version control
• Use appropriate access controls and permissions
• Validate and sanitize inputs to prevent SQL injection

🛠️ Troubleshooting

Common Issues

1. Node.js Path Issues
   • Use which node (Mac/Linux) or where node (Windows) to find correct path
2. File Path Issues
   • Use absolute paths, e.g., /Users/username/projects/supabase-mcp-server/dist/index.js
3. MCP Not Detecting Tools
   • Refresh settings, ensure server runs without errors, verify credentials
4. Permission Issues
   • Ensure dist exists (npm run build)
   • Check file permissions (chmod +x on Unix)

Debug Mode

Enable detailed logs by prefixing command with DEBUG=true:

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

Platform-Specific Notes

• Windows

  "C:\\Program Files\\nodejs\\node.exe" "C:\\path\\to\\dist\\index.js" "postgresql://..."
  

• Linux

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

If issues persist, open an issue with:

• OS details
• Node.js version (node --version)
• Full error message
• Reproduction steps

🤝 Contributing

Contributions are welcome! Feel free to submit a Pull Request.

📄 License

---

Built with ❤️ for the Cursor community
Cursor • Supabase • GitHub