S3 Uploader Server

A Model Context Protocol (MCP) server that provides file upload functionality to AWS S3 buckets with automatic MIME type detection.

Features

• Upload files to S3 buckets
• Automatic MIME type detection based on file extensions
• Support for common file types (images, documents, audio, video, archives)
• Configurable S3 object keys
• Comprehensive error handling

Setup

Prerequisites

• Node.js (version 14 or higher)
• AWS credentials with S3 access
• An S3 bucket

Installation

1. Clone or download this repository
2. Install dependencies:

   npm install
   

Configuration

Set the following environment variables:

export AWS_ACCESS_KEY_ID="your-access-key-id"
export AWS_SECRET_ACCESS_KEY="your-secret-access-key"
export AWS_REGION="your-aws-region"
export BUCKET_NAME="your-s3-bucket-name"

Usage

As an MCP Server

Start the server:

node index.js

The server exposes one tool:

upload_file

Upload a file to the configured S3 bucket.

Parameters:

• filePath (required): Absolute path to the file to upload
• key (optional): S3 object key. If not provided, uses the filename

Example:

{
  "name": "upload_file",
  "arguments": {
    "filePath": "/path/to/your/file.jpg",
    "key": "uploads/my-image.jpg"
  }
}

Supported MIME Types

The server automatically detects MIME types for the following file extensions:

• Images: jpg, jpeg, png, gif, webp, bmp, ico, svg, tiff
• Documents: pdf, doc, docx, xls, xlsx, ppt, pptx, rtf
• Text: txt, csv, html, css, js, json, xml, md
• Audio: mp3, wav, ogg, m4a, flac
• Video: mp4, avi, mov, wmv, flv, webm, mkv
• Archives: zip, rar, tar, gz, 7z
• Other: bin, exe, dmg (treated as binary)

Unknown file types default to application/octet-stream.

Integration with Claude Desktop

To use this MCP server with Claude Desktop, add it to your claude_desktop_config.json:

{
  "mcpServers": {
    "s3-uploader": {
      "command": "node",
      "args": ["/path/to/s3-mcp-server/index.js"],
      "env": {
        "AWS_ACCESS_KEY_ID": "your-access-key-id",
        "AWS_SECRET_ACCESS_KEY": "your-secret-access-key",
        "AWS_REGION": "your-aws-region",
        "BUCKET_NAME": "your-s3-bucket-name"
      }
    }
  }
}

Error Handling

The server provides detailed error messages for common issues:

• Missing environment variables
• File not found
• Invalid file paths
• AWS/S3 errors
• Network connectivity issues

Security Considerations

• Store AWS credentials securely (use environment variables, not hardcoded values)
• Ensure the S3 bucket has appropriate permissions
• Consider using IAM roles instead of access keys in production
• Validate file types and sizes before upload if needed

Development

To test the server locally:

# Test tools listing
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node index.js

# Test file upload (replace with actual file path)
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "upload_file", "arguments": {"filePath": "/path/to/test/file.txt"}}}' | node index.js