AWS S3 MCP Server

A Model Context Protocol (MCP) server that gives AI assistants (Claude, Cursor, etc.) direct access to AWS S3 — enabling them to list, upload, download, and manage S3 buckets and objects through natural language.

Why This Exists

When building AI agent pipelines, you often need agents to read from or write to S3 — whether that's fetching documents for RAG, persisting outputs, or managing files dynamically. This MCP server bridges that gap by exposing S3 operations as MCP tools, so any MCP-compatible AI client can interact with S3 without custom integration work.

Prerequisites

• Node.js 18+
• AWS account with S3 access
• AWS credentials (Access Key ID + Secret, or IAM role)
• An MCP-compatible client (Claude Desktop, Cursor, etc.)

Quick Start

1. Install via npx (no installation needed)

{
  "mcpServers": {
    "aws-s3": {
      "command": "npx",
      "args": ["@gangadharrr/aws-s3"],
      "env": {
        "AWS_REGION": "us-east-1",
        "AWS_ACCESS_KEY_ID": "your-access-key-id",
        "AWS_SECRET_ACCESS_KEY": "your-secret-access-key"
      },
      "autoApprove": ["list_buckets", "list_objects", "get_bucket_policy"]
    }
  }
}

Add this to your MCP client config file:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• Cursor: .cursor/mcp.json in your project root

2. Using AWS CLI credentials (recommended for local dev)

If you've already configured the AWS CLI (aws configure), you can omit the key env vars:

{
  "mcpServers": {
    "aws-s3": {
      "command": "npx",
      "args": ["@gangadharrr/aws-s3"],
      "env": {
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

Available Tools

| Tool | Description | |------|-------------| | list_buckets | List all S3 buckets in the account | | create_bucket | Create a new S3 bucket | | delete_bucket | Delete an empty S3 bucket | | list_objects | List objects in a bucket (with optional prefix filter) | | upload_object | Upload a file or string content to a bucket | | download_object | Download an object from a bucket | | delete_object | Delete an object from a bucket | | get_bucket_policy | Get the policy attached to a bucket | | set_bucket_policy | Set or update a bucket policy |

Tool Reference

list_buckets

Lists all S3 buckets in the AWS account.

Parameters: None

Response:

{
  "success": true,
  "buckets": [
    { "name": "my-bucket", "creationDate": "2023-01-15T00:00:00.000Z" }
  ],
  "count": 1
}

create_bucket

Creates a new S3 bucket.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | bucketName | string | ✅ | Name of the bucket to create | | region | string | ❌ | AWS region (defaults to configured region) |

Response:

{
  "success": true,
  "bucketName": "my-new-bucket",
  "location": "http://my-new-bucket.s3.amazonaws.com/"
}

list_objects

Lists objects in a bucket with optional prefix filtering.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | bucketName | string | ✅ | Bucket to list objects from | | prefix | string | ❌ | Filter by prefix (folder path) | | maxKeys | number | ❌ | Max results (default: 1000) | | continuationToken | string | ❌ | Pagination token |

upload_object

Uploads a file or string content to S3.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | bucketName | string | ✅ | Target bucket | | key | string | ✅ | Object key (path) in the bucket | | filePath | string | ❌ | Local file path to upload | | content | string | ❌ | String content to upload directly | | contentType | string | ❌ | MIME type of the content |

download_object

Downloads an object from S3.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | bucketName | string | ✅ | Source bucket | | key | string | ✅ | Object key (path) to download | | outputPath | string | ❌ | Local path to save the file | | returnContent | boolean | ❌ | Return content inline in response |

delete_object

Deletes an object from a bucket.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | bucketName | string | ✅ | Bucket containing the object | | key | string | ✅ | Object key to delete |

get_bucket_policy / set_bucket_policy

Get or set the IAM policy for a bucket.

Parameters for set_bucket_policy: | Name | Type | Required | Description | |------|------|----------|-------------| | bucketName | string | ✅ | Target bucket | | policy | string/object | ✅ | Policy document (JSON string or object) |

AWS Authentication

The server uses the AWS SDK credential resolution chain in this order:

1. Environment variables — AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY
2. Shared credentials file — ~/.aws/credentials (configured via aws configure)
3. EC2 Instance Metadata — if running on an EC2 instance with an IAM role

For production, IAM roles are recommended over static credentials.

Contributing

Contributions are welcome! If you'd like to add a new S3 operation or improve existing ones:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-new-tool
3. Commit your changes: git commit -m 'Add: new S3 tool'
4. Push and open a Pull Request

License

MIT — see LICENSE for details.

Built with the MCP TypeScript SDK and AWS SDK v3.