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
- Clone the repository:
git clone https://github.com/yourusername/supabase-mcp.git
cd supabase-mcp
- 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
- 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
- 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
- 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
- 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
- Open your AI IDE's settings/preferences
- Navigate to the MCP or AI settings section
- 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
- Open Settings (⌘, or Ctrl+,)
- Go to "AI" section
- Under "MCP Servers", click "Add Server"
- Use the configuration above
- Restart Cursor to apply changes
VS Code with AI Extensions
- Open Command Palette (⌘⇧P or Ctrl+Shift+P)
- Search for "MCP" or "AI Settings"
- Add new MCP server configuration
- Use the configuration above
- Reload VS Code window
JetBrains IDEs with AI Plugins
- Open Settings (⌘, or Ctrl+Alt+S)
- Navigate to "Tools" → "AI" → "MCP Servers"
- Click "+" to add new server
- Use the configuration above
- Restart IDE to apply changes
Verifying MCP Connection
- Check your IDE's status bar for MCP server status
- Look for a green indicator or "MCP Connected" message
- Try using AI features that require database access
- Check Docker logs for any connection issues:
Usage
- Start the MCP server:
- Configure your AI tool to use the MCP server:
{
"mcpServers": {
"supabase": {
"command": "docker-compose",
"args": ["up"]
}
}
}
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
- Fork the repository
- Create a feature branch
- Commit your changes
- Push to the branch
- Create a Pull Request
License
MIT