Provides comprehensive file and bucket management capabilities for Supabase Storage, including secure file uploads, batch operations, image transformations, signed URL generation, and advanced security features with audit logging.
Supabase Storage MCP
A secure, production-ready Model Context Protocol (MCP) server for Supabase Storage with advanced security features, batch operations, and comprehensive file management.
Features
🛡️ Enterprise-Grade Security
Multi-layer Defense: Rate limiting, threat detection, and audit logging
Input Validation: Comprehensive validation with Zod schemas and DOMPurify sanitization
Real-time Monitoring: Security metrics and alert system
Path Traversal Prevention: Advanced protection against directory traversal attacks
File Type Validation: MIME type verification and file signature checking
🗂️ Bucket Management
Secure Bucket Creation: Create storage buckets with security validation
Organized Structure: Automated folder organization for scalable workflows
Batch Setup: Initialize multiple buckets with consistent configuration
🖼️ Advanced File Operations
Batch Upload: Upload 1-500 files with progress tracking and detailed reporting
Dual Input Support: Handle both local file paths and base64 data (Claude Desktop compatible)
File Validation: Size limits, MIME type checking, and signature verification
Transform on Download: Resize, compress, and format images during download
Auto-Download System: Generate JavaScript code for browser downloads
📁 File Management
Secure Downloads: Time-limited signed URLs with access controls
Batch Operations: Process multiple files efficiently
Advanced Search: Filter by extension, folder, and metadata
Custom Filenames: Override default names during download
🔗 Auto-Download Features
Intelligent Triggers: Automatic browser downloads with custom filenames
Batch Downloads: Sequential downloads with configurable delays
JavaScript Generation: Ready-to-use browser scripts
Multiple Formats: Support for signed URLs, base64, and binary data
Installation
Prerequisites
Node.js >= 18.0.0
npm >= 8.0.0
Supabase project with Storage enabled
Setup
Clone and install dependencies:
Configure environment variables:
Edit .env
with your Supabase credentials:
Build the project:
Start the MCP server:
Configuration
Claude Desktop Integration
Add to your Claude Desktop configuration (claude_desktop_config.json
):
Environment Variables
Variable | Required | Description | Default |
| ✅ | Your Supabase project URL | - |
| ✅ | Your Supabase service role key | - |
| ❌ | Environment mode |
|
| ❌ | Logging verbosity |
|
Security Configuration
The server includes comprehensive security features enabled by default:
Rate limiting (100 requests per minute globally)
File size limits (50MB per file, 500 files per batch)
MIME type restrictions (images only by default)
Path traversal protection
Input sanitization
Usage
Basic Bucket Operations
File Upload
File Management
Advanced Downloads
Image Transformations
Security Monitoring
API Reference
Tools
Tool Name | Description |
| Create a new storage bucket |
| Initialize standard bucket structure |
| Upload multiple files with validation |
| List files in bucket with filtering |
| Generate signed download URL |
| Generate multiple signed URLs |
| Download file content with transformations |
| Download with auto-download JavaScript |
| Download multiple files with auto-trigger |
| Get security metrics and status |
File Organization
The server automatically organizes uploaded files in a structured format:
Security
Built-in Protections
Rate Limiting: Prevents API abuse
Input Validation: Sanitizes all inputs
File Validation: MIME type and signature checking
Path Security: Prevents directory traversal
Size Limits: Configurable file and batch size limits
Audit Logging: Complete operation tracking
Security Best Practices
Store your service role key securely
Use environment variables for configuration
Monitor security logs regularly
Keep dependencies updated
Use HTTPS in production
Performance
Batch Upload Performance
Small batches (1-25 files): ~15-30 seconds
Medium batches (26-100 files): ~45-90 seconds
Large batches (101-500 files): ~3-8 minutes
Parallel uploads: 3 concurrent streams
Memory efficient: Streams large files
Download Performance
File URL generation: <50ms per URL
Direct downloads: 100-500ms per file
Batch operations: ~600 files per minute
Transform on download: 200-800ms per image
Development
Build
Development Mode
Security Audit
Contributing
Fork the repository
Create a feature branch (
git checkout -b feature/amazing-feature
)Commit your changes (
git commit -m 'Add amazing feature'
)Push to the branch (
git push origin feature/amazing-feature
)Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Support
Issues: GitHub Issues
Documentation: This README and inline code comments
Community: Discussions
Built with ❤️ for the MCP and Supabase communities.
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Enables secure file and bucket management operations with Supabase Storage through enterprise-grade security features, batch uploads/downloads, and comprehensive file management capabilities. Supports both local file paths and base64 data with advanced transformations and auto-download functionality.