# 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

## 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:
   ```bash
   npm install
   ```

### Configuration

Set the following environment variables:

```bash
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:

```bash
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:**

```json
{
  "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`:

```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:

```bash
# 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
```