Supabase MCP server

This Supabase MCP server enables Claude and other LLMs to perform CRUD operations on Supabase Postgres tables, allowing them to query, insert, update, and delete data directly from your database.

Installation

Install from npm

# Install globally
npm install -g supabase-mcp

# Or install locally in your project
npm install supabase-mcp

Clone the Repository

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

Configuration

Create a .env file with your Supabase credentials:

# Supabase credentials
SUPABASE_URL=your_supabase_project_url
SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key

# MCP server configuration
MCP_SERVER_PORT=3000
MCP_SERVER_HOST=localhost
MCP_API_KEY=your_secret_api_key

Using with Claude

Claude requires a specific transport mode for compatibility:

Claude Desktop MCP Configuration

Add this to your Claude MCP configuration:

"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"
  }
}

Manual Testing with Claude Binary

Test outside of Claude with:

# If installed in project
npm run start:claude

# If installed globally
supabase-mcp-claude

Running as a Standalone Server

Start the MCP server after installing globally:

supabase-mcp

This launches the server at http://localhost:3000 (or your configured port).

Using as a Library

Import and use in your Node.js projects:

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

// Validate configuration
validateConfig();

// Create the server
const app = createServer();

// Start the server
app.listen(mcpConfig.port, mcpConfig.host, () => {
  console.log(`Supabase MCP server running at http://${mcpConfig.host}:${mcpConfig.port}`);
});

Database Operations

Query Data

// Parameters:
// - table (string): Name of the table to query
// - select (string, optional): Comma-separated list of columns (default: "*")
// - query (object, optional): Filter conditions

Insert Data

// Parameters:
// - table (string): Name of the table
// - data (object or array of objects): Data to insert

Update Data

// Parameters:
// - table (string): Name of the table
// - data (object): Data to update as key-value pairs
// - query (object): Filter conditions for the update

Delete Data

// Parameters:
// - table (string): Name of the table
// - query (object): Filter conditions for deletion

List Tables

// Parameters: None

Troubleshooting

Common Issues

Port already in use

• The server tries to find an available port automatically
• You can specify a different port in your .env file by changing MCP_SERVER_PORT

Missing environment variables

• Ensure your .env file contains all required values
• Or set environment variables in your system

TypeError: Class constructor Server cannot be invoked without 'new'

• Update to the latest version: npm install -g supabase-mcp@latest

JSON parsing errors with Claude

• Use the Claude-specific binary (supabase-mcp-claude) instead of the regular HTTP server

Request timeout with Claude

• Check that your Supabase credentials are correct
• Verify the server is running properly
• Ensure nothing is blocking the connection

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.