README.md•5.17 kB
# 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:
```bash
git clone https://github.com/yourusername/supabase-mcp.git
cd supabase-mcp
```
2. Create a `.env` file with your Supabase credentials:
```bash
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:
```bash
# 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
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```json
{
"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:
```bash
docker-compose logs -f
```
## Usage
1. Start the MCP server:
```bash
docker-compose up
```
2. Configure your AI tool to use the MCP server:
```json
{
"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:
```json
{
"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:
```json
{
"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:
```json
{
"table_name": "users",
"filters": { "status": "inactive" },
"updates": { "status": "active" }
}
```
### delete_records
Delete records from a Supabase table based on filter conditions.
Example usage:
```json
{
"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