S3 Uploader MCP 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

Related MCP server: MCP S3 File Uploader

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_files

Upload a file to the configured S3 bucket.

Annotations:

• Title: "Upload File to S3"

• Read-only: false (modifies environment by uploading files)

• Destructive: false (additive operation, doesn't remove existing data)

• Idempotent: false (uploading same file again may overwrite or create new version)

• Open-world: true (interacts with external AWS S3 service)

Parameters:

• filePath (required): Absolute path to the file to upload

• key (optional): S3 object key. If not provided, uses the filename

Example:

{
  "name": "upload_files",
  "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_files", "arguments": {"filePath": "/path/to/test/file.txt"}}}' | node index.js