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:
git clone https://github.com/your-username/supabase-storage-mcp.git
cd supabase-storage-mcp
npm install
- Configure environment variables:
cp .env.example .env
Edit .env with your Supabase credentials:
SUPABASE_URL=https://your-project-id.supabase.co
SUPABASE_SERVICE_KEY=your-service-role-key
NODE_ENV=production
- Build the project:
npm run build
- Start the MCP server:
npm start
Configuration
Claude Desktop Integration
Add to your Claude Desktop configuration (claude_desktop_config.json):
{
"mcpServers": {
"supabase-storage": {
"command": "node",
"args": ["/path/to/supabase-storage-mcp/dist/index.js"],
"description": "Supabase Storage MCP for file and bucket management"
}
}
}
Environment Variables
| Variable | Required | Description | Default |
|---|---|---|---|
SUPABASE_URL | ✅ | Your Supabase project URL | - |
SUPABASE_SERVICE_KEY | ✅ | Your Supabase service role key | - |
NODE_ENV | ❌ | Environment mode | development |
LOG_LEVEL | ❌ | Logging verbosity | info |
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
// Create a storage bucket
await mcp.call('create_bucket', {
bucket_name: 'my-images',
is_public: false
});
// Setup standard bucket structure
await mcp.call('setup_buckets', {
base_bucket_name: 'storage',
user_id: 'user123'
});
File Upload
// Upload multiple images (file paths)
await mcp.call('upload_image_batch', {
bucket_name: 'storage-images',
batch_id: 'batch001',
folder_prefix: 'original',
user_id: 'user123',
image_paths: ['/path/to/image1.jpg', '/path/to/image2.png']
});
// Upload with base64 data (Claude Desktop compatible)
await mcp.call('upload_image_batch', {
bucket_name: 'storage-images',
batch_id: 'batch002',
folder_prefix: 'original',
user_id: 'user123',
image_data: [
{
filename: 'image1.jpg',
content: 'data:image/jpeg;base64,/9j/4AAQSkZJRg...',
mime_type: 'image/jpeg'
}
]
});
File Management
// List files in a bucket
await mcp.call('list_files', {
bucket_name: 'storage-images',
folder_path: 'original/user123',
file_extension: '.jpg'
});
// Generate signed download URLs
await mcp.call('get_file_url', {
bucket_name: 'storage-images',
storage_path: 'original/user123/batch001/image1.jpg',
expires_in: 3600
});
// Batch signed URLs
await mcp.call('create_signed_urls', {
bucket_name: 'storage-images',
file_paths: ['path1.jpg', 'path2.png'],
expires_in: 1800
});
Advanced Downloads
// Download with auto-trigger
await mcp.call('download_file_with_auto_trigger', {
bucket_name: 'storage-images',
file_path: 'original/user123/image1.jpg',
return_format: 'base64',
auto_download: true,
custom_filename: 'my-image.jpg'
});
// Batch download with auto-trigger
await mcp.call('batch_download', {
bucket_name: 'storage-images',
file_paths: ['image1.jpg', 'image2.png'],
return_format: 'signed_url',
auto_download: true,
download_delay: 1000
});
Image Transformations
// Download with transformations
await mcp.call('download_file', {
bucket_name: 'storage-images',
file_path: 'original/image1.jpg',
return_format: 'base64',
transform_options: {
width: 800,
height: 600,
quality: 85
}
});
Security Monitoring
// Get security status
await mcp.call('get_security_status', {});
API Reference
Tools
| Tool Name | Description |
|---|---|
create_bucket | Create a new storage bucket |
setup_buckets | Initialize standard bucket structure |
upload_image_batch | Upload multiple files with validation |
list_files | List files in bucket with filtering |
get_file_url | Generate signed download URL |
create_signed_urls | Generate multiple signed URLs |
download_file | Download file content with transformations |
download_file_with_auto_trigger | Download with auto-download JavaScript |
batch_download | Download multiple files with auto-trigger |
get_security_status | Get security metrics and status |
File Organization
The server automatically organizes uploaded files in a structured format:
bucket-name/
├── original/
│ └── {user_id}/
│ └── {batch_id}/
│ ├── image1.jpg
│ └── image2.png
└── processed/
└── {user_id}/
└── {batch_id}/
├── thumb_image1.jpg
└── optimized_image2.png
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
npm run build
Development Mode
npm run dev
Security Audit
npm run security-check
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.