SB MCP Server

How to use

You connect an MCP client to the server to perform actions on your Supabase database. The Claude integration provides a dedicated stdio transport so Claude can communicate efficiently. You can also run a standalone MCP server locally and integrate it into your own Node.js projects as a library.

How to install

Prerequisites: Install Node.js v16 or newer, and have npm or yarn available. You also need a Supabase project with API keys.

# Install globally (recommended for quick starts)
npm install -g supabase-mcp

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

# If you prefer to build from source, clone the project and install dependencies:

Configuration and runtime tips

Set up your environment with the necessary credentials and server settings. You can run the standalone server or use the Claude transport for Claude integration.

# Example environment file content
# 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

Claude integration and CLI usage

To run Claude-specific integration, use the dedicated Claude transport. The following configuration starts the Claude-compatible MCP proxy using the standard MCP binary.

# Claude Desktop MCP config (example)
"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

For testing outside of Claude, run the Claude-specific binary directly.

npm run start:claude
```

Or, if installed globally:
```
supabase-mcp-claude

Usage as a standalone server

Install the MCP server globally and run it to start listening on the configured host and port.

supabase-mcp
```
This will start the MCP server at http://localhost:3000 by default (adjust via the .env file if you need a different port).

Usage in your code

You can also use the MCP server as a library within your Node.js project. Import the required functions, validate the configuration, create the server, and start listening on the configured port and host.

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}`);
});

Troubleshooting

Common issues and fixes include port conflicts, missing environment variables, and JSON parsing errors when using Claude. Ensure your environment variables are set, the server is running, and you are using the Claude-specific transport when testing with Claude.

queryDatabase

Query data from a table with optional select columns and filter conditions.

insertData

Insert a single object or an array of objects into a specified table.

updateData

Update rows in a table matching given filter conditions with provided data.

deleteData

Delete rows from a table that match the specified filter conditions.

listTables

List all tables available in the connected database.