MCP S3 File Uploader

MCP S3 File Manager

S3 file operations for AI workflows - Upload, download, and manage files in Amazon S3 through Model Context Protocol (MCP).

Perfect for AI assistants like Claude, Cursor, and any MCP-compatible client.

⚡ Quick Start

# Install and run (requires AWS credentials)
uvx mcp-s3 --root ~/uploads

# Or install globally
pip install mcp-s3

🔧 Setup

1. AWS Credentials

Create .env file in your project:

AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_DEFAULT_REGION=us-east-1
S3_BUCKET_NAME=your-bucket-name

2. Add to Your AI Tool

Cursor IDE - Add to settings.json:

{
  "mcp": {
    "servers": {
      "s3": {
        "command": "uvx",
        "args": ["mcp-s3", "--root", "~/uploads"],
        "env": {
          "AWS_ACCESS_KEY_ID": "your_key",
          "AWS_SECRET_ACCESS_KEY": "your_secret", 
          "S3_BUCKET_NAME": "your-bucket"
        }
      }
    }
  }
}

Claude Desktop - Add to config:

{
  "mcpServers": {
    "s3": {
      "command": "mcp-s3",
      "args": ["--root", "~/uploads"],
      "env": {
        "AWS_ACCESS_KEY_ID": "your_key",
        "AWS_SECRET_ACCESS_KEY": "your_secret",
        "S3_BUCKET_NAME": "your-bucket"
      }
    }
  }
}

🛠️ What You Can Do

Upload Files

@mcp Upload my config.json file to S3
@mcp Upload the backup.zip with 2-hour expiration
@mcp Upload report.pdf with force overwrite enabled

Preserves original filenames (config.json → config.json)
Prevents accidental overwrites (fails if file exists)
Force overwrite option for intentional replacements
Progress tracking for large files

Download Files

@mcp Download config.json from S3 to ./downloads/
@mcp Download backup-2024.zip from S3

List Files

@mcp List all files in S3
@mcp List files starting with "logs/"
@mcp Show me the first 50 files in the bucket

Get File Info

@mcp Get info about config.json in S3
@mcp Show details for backup.zip

🚀 For Software Engineers

Common Workflows

1. Backup & Share Code

# Upload project files
@mcp Upload my entire src/ directory to S3
@mcp Generate a 7-day URL for team-config.json

2. CI/CD Integration

# In your deployment scripts
mcp-s3 --root ./build upload dist.tar.gz

3. Log Management

# Upload application logs
@mcp Upload today's error.log to S3
@mcp List all log files from this month

4. Asset Management

# Manage project assets
@mcp Upload design-assets.zip
@mcp Download latest-assets.zip to ./assets/

Development Setup

git clone https://github.com/dayongd1/mcp-s3.git
cd mcp-s3
uv sync
uv run mcp-s3 --root ~/test-uploads

Testing

# Test basic functionality
python examples/test_mcp_server.py

# Test naming conflicts
python examples/test_naming_conflicts.py

# Test all features
python examples/test_download.py
python examples/test_list_files.py
python examples/test_get_file_info.py

🔒 Security Notes

Path Safety: Prevents directory traversal attacks
Credential Management: Uses environment variables (never hardcode keys)
Presigned URLs: Time-limited access (default 24 hours)
Conflict Detection: Prevents accidental file overwrites

📦 Installation Options

# Run without installing (recommended)
uvx mcp-s3

# Install globally
pip install mcp-s3

# Development install
git clone && uv sync

🚨 Troubleshooting

"Bucket not found"

# Check your bucket name and region
aws s3 ls s3://your-bucket-name

"Access denied"

# Verify AWS credentials
python examples/test_aws_connection.py

"File already exists"

# Use force overwrite or rename the file
@mcp Upload config.json with force overwrite enabled

📚 Links

PyPI: https://pypi.org/project/mcp-s3/
GitHub: https://github.com/dayongd1/mcp-s3
MCP Docs: https://modelcontextprotocol.io/
AWS S3 Setup: See AWS_SETUP_GUIDE.md

Built with FastMCP | Python 3.10+ | MIT License

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables secure file uploads to Amazon S3 with progress tracking and presigned URL generation. Provides automatic UUID-based file naming and time-limited access URLs for uploaded files.

Related MCP Servers

s3-tools
sofianhamiti
A
security
F
license
A
quality
An MCP server that provides tools for interacting with AWS S3 buckets, enabling direct access to S3 operations through the Model Context Protocol.
Last updated -
1
Python
S3 MCP Server
samuraikun
A
security
A
license
A
quality
An Amazon S3 Model Context Protocol server that allows Large Language Models like Claude to interact with AWS S3 storage, providing tools for listing buckets, listing objects, and retrieving object contents.
Last updated -
3
684
11
TypeScript
MIT License
AWS S3 MCP Server
OpenWorkspace-o1
-
security
F
license
-
quality
Provides secure access to AWS S3 buckets through pre-signed URLs, enabling listing, downloading, uploading, and deleting objects.
Last updated -
2
TypeScript
Amazon S3 MCP Server by CData
CDataSoftware
-
security
A
license
-
quality
Amazon S3 MCP Server by CData
Last updated -
MIT License

View all related MCP servers