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

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

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.