aws-s3-mcp-server

MCP server for AWS S3 — exposes tools for listing and reading files from S3 buckets.

| Tool | Description | |------|-------------| | s3_list_buckets | List all accessible S3 buckets | | s3_list_objects | List objects in a bucket, with prefix filtering and folder navigation | | s3_read_object | Read file contents (text or binary) from S3 | | s3_get_object_metadata | Get file metadata (size, type, etc.) without downloading |

Usage with Claude Code

claude mcp add aws-s3 -- npx -y @miguel-carrera/aws-s3-mcp-server

Or add to your claude_desktop_config.json / .mcp.json:

Cognito auth (recommended):

{
  "mcpServers": {
    "aws-s3": {
      "command": "npx",
      "args": ["-y", "@miguel-carrera/aws-s3-mcp-server"],
      "env": {
        "AWS_REGION": "us-east-1",
        "COGNITO_IDENTITY_POOL_ID": "<identity-pool-id>",
        "COGNITO_USER_POOL_CLIENT_ID": "<app-client-id>",
        "COGNITO_DOMAIN": "<your-domain>.auth.us-east-1.amazoncognito.com"
      }
    }
  }
}

AWS profile auth:

{
  "mcpServers": {
    "aws-s3": {
      "command": "npx",
      "args": ["-y", "@miguel-carrera/aws-s3-mcp-server"],
      "env": {
        "AWS_REGION": "us-east-1",
        "AWS_PROFILE": "default"
      }
    }
  }
}

Prerequisites

• Node.js ≥ 18

For AWS profile auth: credentials configured in ~/.aws/credentials or ~/.aws/config.

For Cognito auth: a Cognito User Pool with a hosted UI and an Identity Pool. On the first run the server opens your browser to log in; credentials are cached to ~/.atlas-ai/cognito-credentials.json and reused until they expire (~1 hour).

Required IAM permissions:

{
  "Effect": "Allow",
  "Action": [
    "s3:ListAllMyBuckets",
    "s3:ListBucket",
    "s3:GetObject",
    "s3:HeadObject"
  ],
  "Resource": "*"
}

Configuration

| Environment variable | Required | Default | Description | |---|---|---|---| | AWS_REGION | No | us-east-1 | AWS region where your buckets live | | Cognito auth | | | | | COGNITO_IDENTITY_POOL_ID | Yes (Cognito) | — | Cognito Identity Pool ID — activates Cognito auth when set | | COGNITO_USER_POOL_CLIENT_ID | Yes (Cognito) | — | Cognito User Pool app client ID | | COGNITO_DOMAIN | Yes (Cognito) | — | Cognito hosted UI domain (e.g. xyz.auth.us-east-1.amazoncognito.com) | | AWS profile auth | | | | | AWS_PROFILE | No | default | AWS named profile from ~/.aws (used when COGNITO_IDENTITY_POOL_ID is not set) |

Tools

s3_list_buckets

List all S3 buckets accessible with the configured credentials. No parameters required.

s3_list_objects

List objects in a bucket, with optional prefix filtering and folder-style navigation.

| Parameter | Type | Default | Description | |---|---|---|---| | bucket | string | — | S3 bucket name (required) | | prefix | string | "" | Key prefix filter (e.g. "logs/2024/") | | max_keys | number | 100 | Objects to return (1–1000) | | continuation_token | string | — | Pagination token from a previous response | | delimiter | string | — | Group keys into folders (typically "/") |

s3_read_object

Read the contents of an S3 object. Text files are returned as UTF-8; binary files as base64. Text is truncated at 100,000 characters; binary files must be under 5 MB.

| Parameter | Type | Default | Description | |---|---|---|---| | bucket | string | — | S3 bucket name (required) | | key | string | — | Full object key/path (required) | | encoding | auto | utf8 | base64 | auto | Force encoding; auto detects from content-type or extension |

s3_get_object_metadata

Get metadata for an S3 object (size, content type, ETag, custom metadata) without downloading its content. Use this before s3_read_object on unknown or large files.

| Parameter | Type | Default | Description | |---|---|---|---| | bucket | string | — | S3 bucket name (required) | | key | string | — | Full object key/path (required) |

Development

npm install
npm run dev      # watch mode
npm run build    # compile to dist/