Supabase MCP Server

A Model Context Protocol (MCP) server that enables AI tools to interact with Supabase databases. This server provides tools for reading, creating, updating, and deleting records in Supabase tables.

Features

• Read rows from any Supabase table with filtering and column selection
• Create single or multiple records in tables
• Update records based on filter conditions
• Delete records based on filter conditions
• Comprehensive tool descriptions for AI model understanding
• Type-safe request/response handling with Pydantic
• Docker support for easy deployment

Prerequisites

• Python 3.9+
• Docker and Docker Compose
• Supabase project with service role key
• FastMCP-compatible AI IDE

Installation

1. Clone the repository:

git clone https://github.com/yourusername/supabase-mcp.git
cd supabase-mcp

2. Create a .env file with your Supabase credentials:

cp .env.example .env
# Edit .env with your Supabase credentials:
# SUPABASE_URL=your-project-url
# SUPABASE_KEY=your-service-role-key

3. Build and start the container:

# Build and start in detached mode
docker-compose up --build -d

# To view logs
docker-compose logs -f

# To stop the container
docker-compose down

The server will be available at http://localhost:8000.

Docker Management Commands

# Start the container
docker-compose up

# Start in detached mode (background)
docker-compose up -d

# Stop the container
docker-compose down

# View logs
docker-compose logs -f

# Rebuild the container
docker-compose up --build

# Check container status
docker-compose ps

# Restart the container
docker-compose restart

Troubleshooting Docker Issues

1. If the container fails to start:

   # Check logs
   docker-compose logs -f
   
   # Check container status
   docker-compose ps
   
   # Remove and rebuild
   docker-compose down
   docker-compose up --build
   

2. If you get port conflicts:

   # Stop any existing containers using port 8000
   docker-compose down
   
   # Or modify the port in docker-compose.yml
   # ports:
   #   - "8000:8000"  # Change the first number to an available port
   

3. If environment variables aren't loading:

   # Verify .env file exists and has correct values
   cat .env
   
   # Check environment variables in container
   docker-compose exec mcp-server env
   

Configuring MCP in Your AI IDE

General Configuration Steps

1. Open your AI IDE's settings/preferences
2. Navigate to the MCP or AI settings section
3. Add a new MCP server with the following configuration:

{
  "name": "Supabase MCP",
  "command": "docker-compose",
  "args": ["up"],
  "cwd": "/path/to/supabase-mcp"
}

IDE-Specific Instructions

Cursor

1. Open Settings (⌘, or Ctrl+,)
2. Go to "AI" section
3. Under "MCP Servers", click "Add Server"
4. Use the configuration above
5. Restart Cursor to apply changes

VS Code with AI Extensions

1. Open Command Palette (⌘⇧P or Ctrl+Shift+P)
2. Search for "MCP" or "AI Settings"
3. Add new MCP server configuration
4. Use the configuration above
5. Reload VS Code window

JetBrains IDEs with AI Plugins

1. Open Settings (⌘, or Ctrl+Alt+S)
2. Navigate to "Tools" → "AI" → "MCP Servers"
3. Click "+" to add new server
4. Use the configuration above
5. Restart IDE to apply changes

Verifying MCP Connection

1. Check your IDE's status bar for MCP server status
2. Look for a green indicator or "MCP Connected" message
3. Try using AI features that require database access
4. Check Docker logs for any connection issues:

   docker-compose logs -f
   

Usage

1. Start the MCP server:

docker-compose up

2. Configure your AI tool to use the MCP server:

{
  "mcpServers": {
    "supabase": {
      "command": "docker-compose",
      "args": ["up"]
    }
  }
}

Available Tools

read_rows

Read rows from a Supabase table with optional filtering and column selection.

Example usage:

{
  "table_name": "users",
  "columns": ["id", "name"],
  "filters": { "age": { "gt": 18 } },
  "limit": 10
}

create_records

Create one or more records in a Supabase table.

Example usage:

{
  "table_name": "users",
  "records": [
    { "name": "John", "age": 30 },
    { "name": "Jane", "age": 25 }
  ]
}

update_records

Update records in a Supabase table based on filter conditions.

Example usage:

{
  "table_name": "users",
  "filters": { "status": "inactive" },
  "updates": { "status": "active" }
}

delete_records

Delete records from a Supabase table based on filter conditions.

Example usage:

{
  "table_name": "users",
  "filters": { "id": 1 }
}

Security Considerations

• Always use the service role key in a secure environment
• Never expose the service role key in client-side code
• Use appropriate row-level security policies in Supabase
• Consider implementing rate limiting for production use

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

MIT