+-----------------------------------------------------------------------------------+
|  AI Assistant / MCP Client (Claude Code, Claude Desktop, Cursor, Antigravity)     |
+-----------------------------------------------------------------------------------+
                                          |
                             (JSON-RPC via stdio)
                                          v
+-----------------------------------------------------------------------------------+
|  AWS S3 MCP Server (server.py)                                                    |
|  - Multi-Bucket & Access Point Resolver (dynamic override or .env default)        |
|  - Multi-Bucket Broadcast Ingestion (parallel/multi-target put)                   |
|  - Server-Side Cross-Bucket Copy & Move (zero local bandwidth)                    |
|  - Automated Point-in-Time Snapshots & Backup Engine                              |
|  - Universal Object Scanner (extensions, size, regex, timestamps)                |
|  - Safe Content Reader (line/byte pagination, CSV & JSON parsing)                |
|  - Memory-safe streaming downloader with atomic replace                           |
|  - Stderr-only logging (preserves pristine JSON-RPC transport)                    |
+-----------------------------------------------------------------------------------+
                                          |
                               (AWS SigV4 HTTPS / TLS)
                                          v
+-----------------------------------------------------------------------------------+
|  Amazon S3                                                                        |
|  - Primary Buckets (e.g. s3://prod-data-lake)                                     |
|  - Backup / Disaster Recovery Buckets (e.g. s3://dr-backup-vault)                 |
|  - S3 Access Points (arn:aws:s3:<region>:<account>:accesspoint/<name> / alias)    |
|  - Objects: Data (CSV/JSON/Parquet), Docs (PDF), Code, Media, Logs, Binaries      |
+-----------------------------------------------------------------------------------+

# Clone the repository
git clone https://github.com/jnvsainikhil/s3-mcp.git
cd s3-mcp

# Create Python virtual environment
python -m venv .venv

# Activate virtual environment
.\.venv\Scripts\Activate.ps1

# Upgrade pip and install dependencies
pip install --upgrade pip
pip install -r requirements.txt

# Clone the repository
git clone https://github.com/jnvsainikhil/s3-mcp.git
cd s3-mcp

# Create Python virtual environment
python3 -m venv .venv

# Activate virtual environment
source .venv/bin/activate

# Upgrade pip and install dependencies
pip install --upgrade pip
pip install -r requirements.txt

cp .env.example .env

AWS_REGION=us-east-1

# Optional default bucket (multi-bucket mode works even without this!)
S3_BUCKET=my-primary-bucket

# If using AWS CLI profiles or SSO (Recommended):
# AWS_PROFILE=default

# If using direct keys:
# AWS_ACCESS_KEY_ID=AKIAEXAMPLEKEY
# AWS_SECRET_ACCESS_KEY=exampleSecretKey123

# Windows
.\.venv\Scripts\python.exe diagnose_s3.py

# Linux / macOS
python diagnose_s3.py

# Windows
.\.venv\Scripts\python.exe -m pytest -v

# Linux / macOS
pytest -v

# Register project-scoped MCP server:
claude mcp add --scope project s3-mcp -- python server.py

{
  "mcpServers": {
    "s3-mcp": {
      "type": "stdio",
      "command": "python",
      "args": [
        "server.py"
      ],
      "env": {}
    }
  }
}

claude mcp list
claude mcp get s3-mcp

{
  "mcpServers": {
    "s3-mcp": {
      "command": "python",
      "args": [
        "/path/to/s3-mcp/server.py"
      ],
      "env": {
        "AWS_REGION": "us-east-1",
        "S3_BUCKET": "my-s3-bucket",
        "AWS_PROFILE": "default"
      }
    }
  }
}

{
  "name": "s3-mcp",
  "command": "python",
  "args": ["server.py"]
}

# Broadcast config or telemetry to primary and secondary buckets:
write_to_multiple_buckets(
    key="config/global-settings.json",
    content='{"version": "2.4", "replication": true}',
    buckets=["prod-us-east-1", "backup-us-west-2", "dr-eu-central-1"]
)

# Move processed dataset from incoming to warehouse:
move_s3_object(
    source_bucket="raw-data-landing",
    source_key="2026/05/transactions.parquet",
    destination_bucket="analytics-warehouse",
    destination_key="gold/transactions.parquet"
)

# Snapshot entire folder prefix into a backup bucket:
create_s3_backup(
    source_bucket="analytics-warehouse",
    backup_bucket="long-term-archives",
    prefix="gold/",
    timestamp_snapshot=True
)

# Scan all buckets, check permissions, regions, and versioning:
scan_all_buckets(include_details=True)

# Scan for Parquet and CSV files larger than 1MB:
scan_s3_objects(
    bucket="analytics-warehouse",
    prefix="datasets/",
    extensions=[".parquet", ".csv"],
    min_size_bytes=1048576
)