## Overview

This server enables you to:

- Manage S3 buckets and objects
- Handle lifecycle configurations
- Set and retrieve object tags
- Manage bucket policies
- Configure CORS settings

## Installation

There are multiple ways to use this server depending on your setup.

### Cursor (recommended)

Add this to your Cursor MCP configuration:

```json
{
  "mcpServers": {
    "s3-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "AWS_SECRET_ACCESS_KEY=your_access_key",
        "-e",
        "AWS_ACCESS_KEY_ID=your_access_key",
        "-e",
        "AWS_REGION=your_region",
        "ashgw/s3-mcp:latest"
      ]
    }
  }
}
```

> If you prefer pinning to a specific Docker image build (e.g., 20250413-165732), use that tag instead of `latest`. Browse available versions on [Docker Hub](https://hub.docker.com/r/ashgw/s3-mcp/tags).

Cursor will route that request through the MCP server automatically.

Make sure it's green and all the tools are available.
<img width="951" height="430" alt="image" src="https://github.com/user-attachments/assets/c1c0b425-d44b-4cd7-b34d-1621bab2a05d" />

---

### Docker (manual)

You can run the S3 MCP server manually via Docker:

```bash
docker run --rm -it \
  -e AWS_ACCESS_KEY_ID=your_access_key \
  -e AWS_SECRET_ACCESS_KEY=your_secret_key \
  -e AWS_REGION=your_region \
  ashgw/s3-mcp
```

This uses the pre-built image published at [ashgw/s3-mcp](https://hub.docker.com/repository/docker/ashgw/s3-mcp).

---

### Repo

Clone the repository and `cd` into it, then build with:

```bash
docker build -t s3-mcp .
```

Then run with:

```bash
docker run --rm -e AWS_ACCESS_KEY_ID=your_access_key -e AWS_SECRET_ACCESS_KEY=your_secret_key -e AWS_REGION=your_region s3-mcp
```

### Environment Variables

Set the following environment variables for AWS credentials:

```bash
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_REGION=your_region
```

## Features

- **List Buckets**: Retrieve a list of all S3 buckets.
- **Create Bucket**: Create a new S3 bucket with optional configurations.
- **List Objects**: List all objects in a specified bucket.
- **Get Object**: Retrieve the content of a specified object.
- **Put Object**: Upload an object to a specified bucket.
- **Delete Object**: Remove an object from a specified bucket.
- **Generate Presigned URL**: Create a presigned URL for accessing or uploading an object.
- **Set Bucket Policy**: Update or set a policy for a specified bucket.
- **Get Bucket Policy**: Retrieve the current policy for a specified bucket.
- **Delete Bucket Policy**: Remove the current policy for a specified bucket.
- **Lifecycle Configuration**: Manage lifecycle rules for S3 buckets.
- **Object Tagging**: Set and retrieve tags for S3 objects.
- **CORS Configuration**: Get and set CORS rules for a bucket.
- **Copy Object**: Copy an object from one location to another within S3.
- **Download File to Local**: Download a file from a specified S3 bucket to a local path.
- **Upload Local File**: Upload a local file to a specified S3 bucket.

## Few Usage Examples

### List Buckets

```python
response = await tool("list_buckets")
print(response)
```

### Create a Bucket

```python
response = await tool("create_bucket", {
    "bucket_name": "my-new-bucket",
    "region": "us-west-1",
    "config": {
        "blockPublicAccess": {
            "BlockPublicAcls": True,
            "IgnorePublicAcls": True,
            "BlockPublicPolicy": True,
            "RestrictPublicBuckets": True
        },
        "versioning": True,
        "encryption": "AES256"
    }
})
print(response)
```

### Upload a File

```python
response = await tool("upload_local_file", {
    "bucket_name": "my-new-bucket",
    "local_path": "/path/to/local/file.txt",
    "key": "file.txt"
})
print(response)
```

### Get Object Tags

```python
response = await tool("get_object_tagging", {
    "bucket_name": "my-new-bucket",
    "key": "file.txt"
})
print(response)
```

## License

[MIT](/LICENSE)