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

1. Clone and install dependencies:

git clone https://github.com/your-username/supabase-storage-mcp.git
cd supabase-storage-mcp
npm install

2. 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

3. Build the project:

npm run build

4. 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

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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.