s3-mcp-server

MCP server for AWS S3 (and S3-compatible) object storage. Provides tools to list, read, upload, delete, and copy objects — designed for website hosting maintenance and page management.

Features

• Default read-only — write/delete tools are disabled unless ALLOW_WRITE=true is set
• S3-compatible — works with AWS S3, MinIO, Cloudflare R2, Backblaze B2, and other S3-compatible services via AWS_ENDPOINT_URL
• Default bucket — configure once via S3_BUCKET, or pass bucket per tool call

Tools

Read-only (always available)

| Tool | Description | |------|-------------| | s3_list_buckets | List all accessible buckets | | s3_list_objects | List objects with prefix filter, delimiter, and cursor pagination | | s3_head_object | Get object metadata (size, content-type, ETag) without downloading | | s3_get_object | Download object content (text files as UTF-8, binary as base64) | | s3_get_object_url | Return the direct S3 access URL for an object | | s3_get_object_cdn_url | Return the CDN URL for an object (requires CDN_DOMAIN) |

Write (requires ALLOW_WRITE=true)

| Tool | Description | |------|-------------| | s3_put_object | Upload or overwrite an object; auto-detects content-type from extension | | s3_upload_file | Upload a local file as binary (supports images, fonts, PDFs, etc.) | | s3_delete_object | Delete a single object | | s3_delete_objects | Batch delete up to 1000 objects in one request | | s3_copy_object | Copy an object within or between buckets (rename, duplicate) |

Configuration

All sensitive configuration is provided via environment variables in the MCP client config — never hard-coded.

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | AWS_ACCESS_KEY_ID | Yes | — | AWS access key ID | | AWS_SECRET_ACCESS_KEY | Yes | — | AWS secret access key | | AWS_REGION | No | us-east-1 | AWS region | | AWS_ENDPOINT_URL | No | — | Custom endpoint for S3-compatible services | | S3_BUCKET | No | — | Default bucket (tools accept bucket param as override) | | ALLOW_WRITE | No | false | Set to "true" to enable write/delete tools | | CDN_DOMAIN | No | — | CDN domain for s3_get_object_cdn_url (e.g. cdn.example.com) |

Usage

Install and build

npm install
npm run build

Claude Desktop config (claude_desktop_config.json)

Read-only mode (default):

{
  "mcpServers": {
    "s3": {
      "command": "node",
      "args": ["/path/to/s3-mcp-server/dist/index.js"],
      "env": {
        "AWS_ACCESS_KEY_ID": "AKIAIOSFODNN7EXAMPLE",
        "AWS_SECRET_ACCESS_KEY": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
        "AWS_REGION": "us-east-1",
        "S3_BUCKET": "my-website-bucket"
      }
    }
  }
}

Read-write mode:

{
  "mcpServers": {
    "s3": {
      "command": "node",
      "args": ["/path/to/s3-mcp-server/dist/index.js"],
      "env": {
        "AWS_ACCESS_KEY_ID": "AKIAIOSFODNN7EXAMPLE",
        "AWS_SECRET_ACCESS_KEY": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
        "AWS_REGION": "us-east-1",
        "S3_BUCKET": "my-website-bucket",
        "ALLOW_WRITE": "true",
        "CDN_DOMAIN": "cdn.example.com"
      }
    }
  }
}

S3-compatible service (e.g. Cloudflare R2):

{
  "mcpServers": {
    "s3": {
      "command": "node",
      "args": ["/path/to/s3-mcp-server/dist/index.js"],
      "env": {
        "AWS_ACCESS_KEY_ID": "<R2 Access Key ID>",
        "AWS_SECRET_ACCESS_KEY": "<R2 Secret Access Key>",
        "AWS_REGION": "auto",
        "AWS_ENDPOINT_URL": "https://<account-id>.r2.cloudflarestorage.com",
        "S3_BUCKET": "my-site",
        "ALLOW_WRITE": "true"
      }
    }
  }
}

Development

npm run dev    # watch mode with tsx
npm run build  # compile to dist/
npm start      # run compiled server

Security notes

• IAM credentials are read from environment variables injected by the MCP client — they are never stored in code or config files checked into version control
• Write tools (s3_put_object, s3_delete_object, s3_delete_objects, s3_copy_object) are only registered when ALLOW_WRITE=true; they are completely absent from the tool list in read-only mode
• For production use, scope the IAM policy to the minimum required permissions (s3:GetObject, s3:ListBucket, plus s3:PutObject, s3:DeleteObject only when write is needed)