# Setting Up Supabase MCP Server with Cursor (With Debugging)

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
```bash
# 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
```bash
# 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:

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

2. Add the Supabase MCP server configuration:

```json
{
  "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)
```json
{
  "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)
```json
{
  "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:

```bash
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:

```bash
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:

```Dockerfile
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

```bash
docker build -t supabase-mcp .
```

#### 3. Update your Cursor MCP configuration

##### Mac/Linux
```json
{
  "mcpServers": {
    "supabase": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "supabase-mcp"
      ]
    }
  }
}
```

##### Windows
```json
{
  "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:
   ```json
   {
     "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**:
   ```bash
   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](https://supabase.com/docs/guides/getting-started/mcp)
- [Cursor MCP Documentation](https://docs.cursor.com/context/model-context-protocol)
- [Model Context Protocol](https://www.anthropic.com/news/model-context-protocol)