MCP S3

🚀 MCP S3 File Manager

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

It's 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

✨ Features

• Upload Files: Preserves original filenames, prevents accidental overwrites, has a force overwrite option, and supports progress tracking for large files.
• Download Files: Allows you to download files from S3 to specified locations.
• List Files: Enables listing all files or files starting with a specific prefix in S3.
• Get File Info: Provides detailed information about files in S3.

📦 Installation

# Run without installing (recommended)
uvx mcp-s3

# Install globally
pip install mcp-s3

# Development install
git clone && uv sync

💻 Usage Examples

Basic Usage

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

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

Advanced Usage

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

🔧 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"
      }
    }
  }
}

🔧 Technical Details

• 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

🚨 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

📚 Documentation

• 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

📄 License

This project is under the MIT License.