S3 Upload MCP Server

A Model Context Protocol (MCP) server that provides image upload capabilities to AWS S3 with public URL generation and bucket management.

Features

• Upload images directly from base64 data or local filesystem
• Generate signed public URLs for S3 objects
• Create and manage S3 buckets with public read policies
• Pure Node.js implementation - no Python dependencies
• High-performance image validation using Sharp (format, size, dimensions)
• Buffer-based MIME type detection with file-type
• Unique filename generation with timestamps and UUIDs
• Support for multiple image formats (JPEG, PNG, GIF, WebP, BMP)
• Built with AWS SDK v3 for optimal performance

Installation

Via NPM (Recommended)

npm install -g @andrewlwn77/s3-upload-mcp-server

From Source

git clone https://github.com/andrewlwn77/s3-upload-mcp-server.git
cd s3-upload-mcp-server
npm install
npm run build

Prerequisites

System Dependencies

Pure Node.js implementation - no Python dependencies required! The server uses:

• Sharp: High-performance image processing and validation
• file-type: MIME type detection from file buffers
• AWS SDK v3: Modern AWS S3 integration

All dependencies are automatically installed via npm.

AWS Configuration

Set up your AWS credentials and configuration:

export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export AWS_DEFAULT_REGION="us-east-1"
export S3_BUCKET_NAME="your-default-bucket"  # Optional

Required AWS Permissions

Your AWS credentials need the following S3 permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:ListBucket",
        "s3:CreateBucket",
        "s3:PutBucketPolicy",
        "s3:GetBucketLocation"
      ],
      "Resource": [
        "arn:aws:s3:::your-bucket-name",
        "arn:aws:s3:::your-bucket-name/*"
      ]
    }
  ]
}

Usage

As MCP Server

Add to your MCP configuration file (.mcp.json):

{
  "mcpServers": {
    "s3-upload": {
      "command": "npx",
      "args": ["-y", "@andrewlwn77/s3-upload-mcp-server"],
      "env": {
        "AWS_ACCESS_KEY_ID": "your-access-key",
        "AWS_SECRET_ACCESS_KEY": "your-secret-key",
        "AWS_DEFAULT_REGION": "us-east-1",
        "S3_BUCKET_NAME": "your-default-bucket"
      }
    }
  }
}

Direct Execution

s3-upload-mcp-server

Available Tools

1. upload_image_to_s3

Upload image data directly to S3 bucket.

Parameters:

• image_data (string, required): Base64 encoded image data
• filename (string, required): Desired filename with extension
• bucket (string, optional): S3 bucket name
• content_type (string, optional): MIME type

Example:

{
  "image_data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==",
  "filename": "test-image.png",
  "bucket": "my-image-bucket"
}

2. upload_image_file_to_s3

Upload image file from local filesystem.

Parameters:

• file_path (string, required): Local path to image file
• bucket (string, optional): S3 bucket name
• key (string, optional): S3 object key
• preserve_filename (boolean, optional): Preserve original filename

Example:

{
  "file_path": "/path/to/image.jpg",
  "bucket": "my-image-bucket",
  "preserve_filename": true
}

3. generate_public_url

Generate signed public URL for S3 object.

Parameters:

• bucket (string, required): S3 bucket name
• key (string, required): S3 object key
• expiration (integer, optional): URL expiration in seconds (300-604800)

Example:

{
  "bucket": "my-image-bucket",
  "key": "images/photo.jpg",
  "expiration": 3600
}

4. create_bucket_if_not_exists

Create S3 bucket with proper configuration.

Parameters:

• bucket_name (string, required): Bucket name (3-63 chars, lowercase)
• region (string, optional): AWS region
• enable_public_read (boolean, optional): Enable public read access

Example:

{
  "bucket_name": "my-new-bucket",
  "region": "us-west-2",
  "enable_public_read": true
}

5. set_bucket_public_read_policy

Configure bucket for public read access.

Parameters:

• bucket_name (string, required): S3 bucket name

Example:

{
  "bucket_name": "my-bucket"
}

6. generate_unique_filename

Generate unique filename with timestamp and UUID.

Parameters:

• original_name (string, required): Original filename
• prefix (string, optional): Optional prefix
• include_timestamp (boolean, optional): Include timestamp

Example:

{
  "original_name": "photo.jpg",
  "prefix": "user_upload",
  "include_timestamp": true
}

7. validate_image_format

Validate image file format and properties.

Parameters:

• file_path (string, required): Path to image file
• max_file_size (integer, optional): Maximum file size in bytes

Example:

{
  "file_path": "/path/to/image.jpg",
  "max_file_size": 5242880
}

Configuration

Environment Variables

| Variable | Required | Description | Default | |----------|----------|-------------|---------| | AWS_ACCESS_KEY_ID | ✅ | AWS access key ID | - | | AWS_SECRET_ACCESS_KEY | ✅ | AWS secret access key | - | | AWS_DEFAULT_REGION | ✅ | AWS region | us-east-1 | | S3_BUCKET_NAME | ⚪ | Default S3 bucket name | - | | LOG_LEVEL | ⚪ | Logging level (ERROR, WARN, INFO, DEBUG) | INFO | | MAX_FILE_SIZE | ⚪ | Maximum file size in bytes | 10485760 |

Supported Image Formats

• JPEG (.jpg, .jpeg)
• PNG (.png)
• GIF (.gif)
• WebP (.webp)
• BMP (.bmp)

File Size Limits

• Default maximum: 10MB (10,485,760 bytes)
• Configurable via MAX_FILE_SIZE environment variable
• Large files (>5MB) use multipart upload automatically

Error Handling

All tools return structured responses with success status and error details:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "File size exceeds maximum allowed",
    "details": {},
    "retry_after": 300
  }
}

Error Codes

• AUTH_ERROR: AWS authentication failed
• BUCKET_ERROR: S3 bucket operation failed
• UPLOAD_ERROR: File upload failed
• VALIDATION_ERROR: Input validation failed
• FILE_ERROR: File system operation failed
• NETWORK_ERROR: Network connectivity issues

Development

Building

npm run build

Testing

npm test

Development Mode

npm run dev

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues and questions:

• GitHub Issues: https://github.com/andrewlwn77/s3-upload-mcp-server/issues
• Documentation: See this README and inline code documentation