I Had a hell of a time getting my Supabase MCP Server working. I figured that, because I went through the ringer on figuring out how to fix it, that I would share with you all that are probably googling how to get it fixed a guide to do just that.

If you're unaware, the current official MCP server for Supabase seems to not be working very well at the moment: https://github.com/supabase-community/supabase-mcp/issues/28

Setting Up Supabase MCP Server with Cursor

This guide walks through setting up the Supabase Model Context Protocol (MCP) server with Cursor, allowing you to interact with your Supabase database directly through Cursor's AI assistant.

Prerequisites

• A Supabase account with a project
• Cursor IDE installed
• Node.js installed (v18+ recommended)
• A Supabase Personal Access Token (PAT)

Step 1: Generate a Supabase Personal Access Token

1. Log in to your Supabase account at https://supabase.com/dashboard
2. Click on your profile icon in the top right corner
3. Select "Access Tokens" from the dropdown menu
4. Click "Generate new token"
5. Give your token a name (e.g., "Cursor MCP")
6. Copy the generated token (it starts with sbp_)

Step 2: Install Required Packages

The Supabase MCP server requires specific packages to work properly. Install them locally in a dedicated directory:

Mac

# Create a directory for MCP packages
mkdir -p ~/.cursor/mcp-packages

# Navigate to the directory
cd ~/.cursor/mcp-packages

# Initialize a package.json
npm init -y

# Install required packages
npm install @supabase/mcp-server-supabase @modelcontextprotocol/sdk

Windows

# Create a directory for MCP packages
mkdir -p %APPDATA%\Cursor\mcp-packages

# Navigate to the directory
cd %APPDATA%\Cursor\mcp-packages

# Initialize a package.json
npm init -y

# Install required packages
npm install @supabase/mcp-server-supabase @modelcontextprotocol/sdk

Step 3: Configure Cursor's MCP Server

Mac Setup

1. Create or edit your Cursor MCP configuration file:

mkdir -p ~/.cursor
touch ~/.cursor/mcp.json

2. Add the Supabase MCP server configuration:

{
  "mcpServers": {
    "supabase": {
      "command": "node",
      "args": [
        "/Users/YOUR_USERNAME/.cursor/mcp-packages/node_modules/@supabase/mcp-server-supabase/dist/stdio.js",
        "--access-token",
        "YOUR_SUPABASE_PAT_HERE"
      ]
    }
  }
}

3. Replace:
   • YOUR_USERNAME with your Mac username
   • YOUR_SUPABASE_PAT_HERE with your Supabase Personal Access Token

Windows Setup

1. Create or edit your Cursor MCP configuration file at %APPDATA%\Cursor\mcp.json

2. Add the Supabase MCP server configuration:

Option 1: Using npx (simpler but might have dependency issues)

{
  "mcpServers": {
    "supabase": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@supabase/mcp-server-supabase",
        "--access-token",
        "YOUR_SUPABASE_PAT_HERE"
      ]
    }
  }
}

Note: We're intentionally omitting @latest to avoid potential dependency conflicts.

Option 2: Using locally installed packages (more reliable)

{
  "mcpServers": {
    "supabase": {
      "command": "cmd",
      "args": [
        "/c",
        "node",
        "%APPDATA%\\Cursor\\mcp-packages\\node_modules\\@supabase\\mcp-server-supabase\\dist\\stdio.js",
        "--access-token",
        "YOUR_SUPABASE_PAT_HERE"
      ]
    }
  }
}

3. Replace YOUR_SUPABASE_PAT_HERE with your Supabase Personal Access Token

Step 4: Verify the MCP Server Path

Mac

1. Make sure the path to the stdio.js file is correct:

ls -la ~/.cursor/mcp-packages/node_modules/@supabase/mcp-server-supabase/dist/

2. Confirm that stdio.js exists in this directory and is executable.

Windows

1. Make sure the path to the stdio.js file is correct:

dir %APPDATA%\Cursor\mcp-packages\node_modules\@supabase\mcp-server-supabase\dist\

2. Confirm that stdio.js exists in this directory.

Step 5: Restart Cursor

1. Completely close Cursor
2. Reopen Cursor
3. The Supabase MCP server should now be available

Security Considerations and Docker Alternative

The setup described above runs the MCP server directly on your system, which has some security implications:

Potential Vulnerabilities

1. Access Token Exposure: Your Supabase PAT is stored in a plaintext file on your system
2. Dependency Security: The MCP server and its dependencies run with your user permissions
3. Network Access: The server has direct network access to Supabase from your machine

Docker-Based Alternative (More Secure)

Using Docker provides better isolation and security. Here's how to set it up:

1. Create a Dockerfile

Create a file named Dockerfile in a directory of your choice:

FROM node:18-slim

RUN npm install -g @supabase/mcp-server-supabase @modelcontextprotocol/sdk

ENTRYPOINT ["supabase-mcp", "--access-token"]
CMD ["YOUR_SUPABASE_PAT_HERE"]

Replace YOUR_SUPABASE_PAT_HERE with your Supabase PAT.

2. Build the Docker image

docker build -t supabase-mcp .

3. Update your Cursor MCP configuration

Mac/Linux

{
  "mcpServers": {
    "supabase": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "supabase-mcp"
      ]
    }
  }
}

Windows

{
  "mcpServers": {
    "supabase": {
      "command": "cmd",
      "args": [
        "/c",
        "docker",
        "run",
        "-i",
        "--rm",
        "supabase-mcp"
      ]
    }
  }
}

Security Best Practices

Regardless of which approach you choose:

1. Limit Token Permissions: Create a Supabase PAT with the minimum necessary permissions
2. Regular Updates: Keep the MCP server and dependencies updated
3. Monitor Access: Regularly audit your Supabase logs for unusual activity
4. Token Rotation: Periodically rotate your PAT for enhanced security
5. Local Network: Consider running the MCP server on a trusted local network only

Troubleshooting

Error: Cannot find module

If you see an error message like:

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '@modelcontextprotocol/sdk/dist/esm/server/stdio.js'

Try the following solutions (in order of simplicity):

1. Remove @latest from npx command:

   • If you're using the npx approach with @latest suffix, remove it:

     {
     "mcpServers": {
       "supabase": {
         "command": "npx",
         "args": [
           "-y",
           "@supabase/mcp-server-supabase",
           "--access-token",
           "YOUR_SUPABASE_PAT_HERE"
         ]
       }
     }
     }
     

   • This simple change often resolves dependency conflicts

2. Use a direct local installation:

   • Make sure you've installed the packages in the correct directory
   • Check that you're using the absolute path in your configuration
   • Point directly to the stdio.js file

3. Try global installation:

   npm install -g @supabase/mcp-server-supabase @modelcontextprotocol/sdk
   

4. For Windows users:

   • Check that you're using the correct path with double backslashes in your configuration
   • If using the npx method, try switching to the local installation method

Configuration not working

1. Check your JSON syntax in mcp.json (no trailing commas, proper nesting)
2. Verify that your PAT is valid and not expired
3. Ensure you're pointing to the correct file (stdio.js, not cli.js)
4. On Windows, make sure paths use double backslashes (\\) in the JSON configuration

Using the Supabase MCP Server

Once configured, you can interact with your Supabase database through Cursor's AI assistant:

1. Ask for information about your Supabase projects
2. Query your database tables
3. Insert, update, or delete data
4. Work with Supabase storage, authentication, and functions

Example prompts:

• "Show me the schema of my Supabase database"
• "List all users in my Supabase project"
• "Create a new table in my Supabase database"
• "Query all documents created in the last week"

Resources

• Supabase MCP Documentation
• Cursor MCP Documentation
• Model Context Protocol