toddalchin/mcp-supabase-proxy

MCP Supabase Proxy Server

A proxy server that routes Supabase MCP tool requests to multiple Supabase instances, solving the limitation where Cursor (and other MCP clients) can't properly distinguish between multiple servers of the same type.

Problem

When you have multiple Supabase MCP servers configured, Cursor's tool selection mechanism doesn't distinguish between them properly - it just defaults to the first matching tool name it finds. This proxy solves that by adding a project_id parameter to all tools and routing requests to the appropriate Supabase instance.

How It Works

The proxy server:

1. Maintains a connection pool of MCP clients, one per Supabase project
2. Spawns the official @supabase/mcp-server-supabase server for each project on-demand
3. Adds a project_id parameter to all Supabase tools
4. Routes requests to the appropriate Supabase instance based on the project_id parameter

Setup

1. Install Dependencies

npm install

2. Configure Projects

Copy the example config file and add your Supabase projects:

cp projects.example.json projects.json

Edit projects.json and add your projects:

{
  "my-project": {
    "name": "My Project",
    "accessToken": "sbp_your_access_token_here",
    "projectRef": "your_project_ref_here",
    "serviceRoleKey": "eyJhbGc...your_service_role_key_here"
  }
}

Getting your credentials:

• Access Token: Get from Supabase Dashboard → Settings → Access Tokens
• Project Ref: Found in your project URL: https://app.supabase.com/project/[PROJECT_REF] or in your project settings
• Service Role Key (optional): Get from Supabase Dashboard → Settings → API → Service Role Key (use for admin operations)

3. Build

npm run build

4. Configure Cursor (or your MCP client)

Add to your mcp.json:

{
  "mcpServers": {
    "supabase-proxy": {
      "command": "node",
      "args": ["/path/to/mcp-supabase-proxy/dist/index.js"]
    }
  }
}

Important: Use the absolute path to dist/index.js in your mcp.json.

5. Restart Cursor

Restart Cursor to load the new MCP server configuration.

Usage

All Supabase MCP tools now require a project_id parameter. The project_id is the key you use in your projects.json file.

List Available Projects

list_projects()

Get Service Role Key

get_service_role_key(project_id: "my-project")

Note: This only works if you've configured a serviceRoleKey in your projects.json file.

Example Tool Calls

List tables:

list_tables(project_id: "my-project", schemas: ["public"])

Execute SQL:

execute_sql(project_id: "my-project", query: "SELECT * FROM users LIMIT 10")

Get project URL:

get_project_url(project_id: "my-project")

Apply migration:

apply_migration(
  project_id: "my-project",
  name: "add_users_table",
  query: "CREATE TABLE users (id uuid PRIMARY KEY, name text)"
)

Adding More Projects

1. Edit projects.json
2. Add a new entry with a unique key (this becomes the project_id)
3. Rebuild: npm run build
4. Restart Cursor

Example:

{
  "production": {
    "name": "Production Database",
    "accessToken": "sbp_prod_token",
    "projectRef": "prod_ref"
  },
  "staging": {
    "name": "Staging Database",
    "accessToken": "sbp_staging_token",
    "projectRef": "staging_ref"
  }
}

Development

# Build
npm run build

# Watch mode (rebuilds on changes)
npm run dev

# Run directly
npm start

Architecture

The proxy uses the MCP SDK to:

• Act as an MCP server (receiving requests from Cursor)
• Act as MCP clients (forwarding requests to individual Supabase MCP servers)
• Cache client connections for efficiency
• Automatically clean up connections when they close

Security Notes

• Never commit projects.json - Add it to .gitignore
• Keep your access tokens secure
• The projects.example.json file is safe to commit (it contains no real credentials)

Troubleshooting

"Config file not found"

• Make sure projects.json exists in the project root
• Check that the path in mcp.json is correct

"Unknown project_id"

• Verify the project_id matches a key in projects.json
• Call list_projects() to see available projects

Connection errors

• Verify your access tokens are valid
• Check that your project refs are correct
• Ensure you have network access to Supabase

License

MIT