Skip to main content
Glama

Supabase Storage MCP

by Desmond-Labs

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
  1. 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
  1. Build the project:

npm run build
  1. 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


Built with ā¤ļø for the MCP and Supabase communities.

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Desmond-Labs/supabase-storage-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server