# Supabase MCP Server [](https://smithery.ai/server/supabase-server) A Model Context Protocol (MCP) server that provides comprehensive tools for interacting with Supabase databases, storage, and edge functions. This server enables seamless integration between Supabase services and MCP-compatible applications. ## Overview The Supabase MCP server acts as a bridge between MCP clients and Supabase's suite of services, providing: - Database operations with rich querying capabilities - Storage management for files and assets - Edge function invocation - Project and organization management - User authentication and management - Role-based access control ## Architecture The server is built using TypeScript and follows a modular architecture: \`\`\` supabase-server/ ├── src/ │ ├── index.ts # Main server implementation │ └── types/ │ └── supabase.d.ts # Type definitions ├── package.json ├── tsconfig.json ├── config.json.example # Example configuration file └── .env.example # Environment variables template \`\`\` ### Key Components - **Server Class**: Implements the MCP server interface and handles all client requests - **Type Definitions**: Comprehensive TypeScript definitions for all operations - **Environment Configuration**: Secure configuration management via environment variables - **Error Handling**: Robust error handling with detailed error messages ## Prerequisites - Node.js 16.x or higher - A Supabase project with: - Project URL - Service Role Key (for admin operations) - Access Token (for management operations) - MCP-compatible client ## Installation ### Installing via Smithery To install Supabase Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/supabase-server): \`\`\`bash npx -y @smithery/cli install supabase-server --client claude \`\`\` 1. Clone the repository: \`\`\`bash git clone https://github.com/DynamicEndpoints/supabase-mcp.git cd supabase-mcp \`\`\` 2. Install dependencies: \`\`\`bash npm install \`\`\` 3. Create environment configuration: \`\`\`bash cp .env.example .env \`\`\` 4. Configure environment variables: \`\`\`bash SUPABASE_URL=your_project_url_here SUPABASE_KEY=your_service_role_key_here SUPABASE_ACCESS_TOKEN=your_access_token_here # Required for management operations \`\`\` 5. Create server configuration: \`\`\`bash cp config.json.example config.json \`\`\` 6. Build the server: \`\`\`bash npm run build \`\`\` ## Configuration The server supports extensive configuration through both environment variables and a config.json file. Here's a detailed breakdown of the configuration options: ### Server Configuration \`\`\`json \{ "server": \{ "name": "supabase-server", // Server name "version": "0.1.0", // Server version "port": 3000, // Port number (if running standalone) "host": "localhost" // Host address (if running standalone) \} \} \`\`\` ### Supabase Configuration \`\`\`json \{ "supabase": \{ "project": \{ "url": "your_project_url", "key": "your_service_role_key", "accessToken": "your_access_token" \}, "storage": \{ "defaultBucket": "public", // Default storage bucket "maxFileSize": 52428800, // Max file size in bytes (50MB) "allowedMimeTypes": [ // Allowed file types "image/*", "application/pdf", "text/*" ] \}, "database": \{ "maxConnections": 10, // Max DB connections "timeout": 30000, // Query timeout in ms "ssl": true // SSL connection \}, "auth": \{ "autoConfirmUsers": false, // Auto-confirm new users "disableSignup": false, // Disable public signups "jwt": \{ "expiresIn": "1h", // Token expiration "algorithm": "HS256" // JWT algorithm \} \} \} \} \`\`\` ### Logging Configuration \`\`\`json \{ "logging": \{ "level": "info", // Log level "format": "json", // Log format "outputs": ["console", "file"], // Output destinations "file": \{ "path": "logs/server.log", // Log file path "maxSize": "10m", // Max file size "maxFiles": 5 // Max number of files \} \} \} \`\`\` ### Security Configuration \`\`\`json \{ "security": \{ "cors": \{ "enabled": true, "origins": ["*"], "methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"], "allowedHeaders": ["Content-Type", "Authorization"] \}, "rateLimit": \{ "enabled": true, "windowMs": 900000, // 15 minutes "max": 100 // Max requests per window \} \} \} \`\`\` ### Monitoring Configuration \`\`\`json \{ "monitoring": \{ "enabled": true, "metrics": \{ "collect": true, "interval": 60000 // Collection interval in ms \}, "health": \{ "enabled": true, "path": "/health" // Health check endpoint \} \} \} \`\`\` See \`config.json.example\` for a complete example configuration file. ## MCP Integration Add the server to your MCP settings (cline_mcp_settings.json): \`\`\`json \{ "mcpServers": \{ "supabase": \{ "command": "node", "args": ["path/to/supabase-server/build/index.js"], "env": \{ "SUPABASE_URL": "your_project_url", "SUPABASE_KEY": "your_service_role_key", "SUPABASE_ACCESS_TOKEN": "your_access_token" \}, "config": "path/to/config.json" // Optional: path to configuration file \} \} \} \`\`\` ## Available Tools ### Database Operations #### create_record Create a new record in a table with support for returning specific fields. \`\`\`typescript \{ table: string; data: Record; returning?: string[]; \} \`\`\` Example: \`\`\`typescript \{ table: "users", data: \{ name: "John Doe", email: "john@example.com" \}, returning: ["id", "created_at"] \} \`\`\` #### read_records Read records with advanced filtering, joins, and field selection. \`\`\`typescript \{ table: string; select?: string[]; filter?: Record; joins?: Array<\{ type?: 'inner' | 'left' | 'right' | 'full'; table: string; on: string; \}>; \} \`\`\` Example: \`\`\`typescript \{ table: "posts", select: ["id", "title", "user.name"], filter: \{ published: true \}, joins: [\{ type: "left", table: "users", on: "posts.user_id=users.id" \}] \} \`\`\` #### update_record Update records with filtering and returning capabilities. \`\`\`typescript \{ table: string; data: Record; filter?: Record; returning?: string[]; \} \`\`\` Example: \`\`\`typescript \{ table: "users", data: \{ status: "active" \}, filter: \{ email: "john@example.com" \}, returning: ["id", "status", "updated_at"] \} \`\`\` #### delete_record Delete records with filtering and returning capabilities. \`\`\`typescript \{ table: string; filter?: Record; returning?: string[]; \} \`\`\` Example: \`\`\`typescript \{ table: "posts", filter: \{ status: "draft" \}, returning: ["id", "title"] \} \`\`\` ### Storage Operations #### upload_file Upload files to Supabase Storage with configurable options. \`\`\`typescript \{ bucket: string; path: string; file: File | Blob; options?: \{ cacheControl?: string; contentType?: string; upsert?: boolean; \}; \} \`\`\` Example: \`\`\`typescript \{ bucket: "avatars", path: "users/123/profile.jpg", file: imageBlob, options: \{ contentType: "image/jpeg", upsert: true \} \} \`\`\` #### download_file Download files from Supabase Storage. \`\`\`typescript \{ bucket: string; path: string; \} \`\`\` Example: \`\`\`typescript \{ bucket: "documents", path: "reports/annual-2023.pdf" \} \`\`\` ### Edge Functions #### invoke_function Invoke Supabase Edge Functions with parameters and custom options. \`\`\`typescript \{ function: string; params?: Record; options?: \{ headers?: Record; responseType?: 'json' | 'text' | 'arraybuffer'; \}; \} \`\`\` Example: \`\`\`typescript \{ function: "process-image", params: \{ url: "https://example.com/image.jpg", width: 800 \}, options: \{ responseType: "json" \} \} \`\`\` ### User Management #### list_users List users with pagination support. \`\`\`typescript \{ page?: number; per_page?: number; \} \`\`\` #### create_user Create a new user with metadata. \`\`\`typescript \{ email: string; password: string; data?: Record; \} \`\`\` #### update_user Update user details. \`\`\`typescript \{ user_id: string; email?: string; password?: string; data?: Record; \} \`\`\` #### delete_user Delete a user. \`\`\`typescript \{ user_id: string; \} \`\`\` #### assign_user_role Assign a role to a user. \`\`\`typescript \{ user_id: string; role: string; \} \`\`\` #### remove_user_role Remove a role from a user. \`\`\`typescript \{ user_id: string; role: string; \} \`\`\` ## Error Handling The server provides detailed error messages for common scenarios: - Invalid parameters - Authentication failures - Permission issues - Rate limiting - Network errors - Database constraints Errors are returned in a standardized format: \`\`\`typescript \{ code: ErrorCode; message: string; details?: any; \} \`\`\` ## Development ### Running Tests \`\`\`bash npm test \`\`\` ### Building \`\`\`bash npm run build \`\`\` ### Linting \`\`\`bash npm run lint \`\`\` ### Running evals The evals package loads an mcp client that then runs the index.ts file, so there is no need to rebuild between tests. You can load environment variables by prefixing the npx command. Full documentation can be found [here](https://www.mcpevals.io/docs). \`\`\`bash OPENAI_API_KEY=your-key npx mcp-eval src/evals/evals.ts src/index.ts \`\`\` ## 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 License - see LICENSE for details ## Support For support, please: 1. Check the [issues](https://github.com/DynamicEndpoints/supabase-mcp/issues) for existing problems/solutions 2. Create a new issue with detailed reproduction steps 3. Include relevant error messages and environment details