Supabase MCP Server

How to use

With an MCP client, connect to the Supabase MCP Server to perform common data and storage operations, invoke edge functions, and manage users and roles. You will interact through the MCP layer, which translates your requests into Supabase API calls and returns structured results or errors.

How to install

# Prerequisites
- Node.js 16.x or higher
- Git

# Optional: install via Smithery for Claude Desktop automation
npx -y @smithery/cli install supabase-server --client claude

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

# Install dependencies
npm install

# Create environment configuration
cp .env.example .env

# Configure environment variables (fill in your values)
# SUPABASE_URL=your_project_url_here
# SUPABASE_KEY=your_service_role_key_here
# SUPABASE_ACCESS_TOKEN=your_access_token_here

# Create server configuration
cp config.json.example config.json

# Build the server (if you will run as a standalone process)
npm run build

# Start the server (example, if you use the built output)
node dist/index.js

Additional configuration and usage notes

The server can be configured using environment variables and a separate configuration file. You can tune database connections, storage limits, logging, security, and monitoring to fit your deployment. When running, you can point your MCP client to the local server or to a remote endpoint once exposed.

Configuration

{
  "server": {
    "name": "supabase-server",
    "version": "0.1.0",
    "port": 3000,
    "host": "localhost"
  }
}

Security

{
  "security": {
    "cors": {
      "enabled": true,
      "origins": ["*"],
      "methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
      "allowedHeaders": ["Content-Type", "Authorization"]
    },
    "rateLimit": {
      "enabled": true,
      "windowMs": 900000,
      "max": 100
    }
  }
}

MCP integration and how to run

{
  "mcpServers": {
    "supabase": {
      "command": "node",
      "args": ["path/to/supabase-server/build/index.js"],
      "env": {
        "SUPABASE_URL": "your_project_url",
        "SUPABASE_KEY": "your_service_role_key",
        "SUPABASE_ACCESS_TOKEN": "your_access_token"
      },
      "config": "path/to/config.json"
    }
  }
}

Tools and capabilities

The server exposes a comprehensive set of capabilities to manage data, storage, functions, and users through MCP endpoints. Key operations include creating, reading, updating, and deleting records; uploading and downloading storage files; invoking edge functions; and managing users and their roles.

Troubleshooting

If you encounter authentication or permission errors, verify that your Supabase credentials and access tokens are correctly configured in the environment variables. Check network access, CORS settings, and that the MCP server process has the necessary permissions to reach your Supabase project.

Notes

Keep your server dependencies up to date and monitor the logs for any errors or slow queries. Adjust the database timeout, max connections, and storage limits to balance performance and resource usage in your deployment.

create_record

Create a new record in a table with optional returning fields to fetch specific columns after insertion.

read_records

Read records with advanced filtering, joins, and field selection to shape the result set.

update_record

Update records with filtering and optional returning fields to retrieve updated values.

delete_record

Delete records with filtering and optional returning fields to retrieve deleted identifiers.

upload_file

Upload files to Storage with configurable bucket, path, and options like content type and upsert behavior.

download_file

Download files from Storage by bucket and path.

invoke_function

Invoke Supabase Edge Functions with parameters and optional headers and response type.

list_users

List users with optional pagination to manage a user base.

create_user

Create a new user with optional metadata.

update_user

Update user details and metadata.

delete_user

Delete a user by identifier.

assign_user_role

Assign a role to a user to grant permissions.

remove_user_role

Remove a role from a user to revoke permissions.