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 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:

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:

`upload_object`

Uploads a file or string content to S3.

Parameters:

`download_object`

Downloads an object from S3.

Parameters:

`delete_object`

Deletes an object from a bucket.

Parameters:

`get_bucket_policy` / `set_bucket_policy`

Get or set the IAM policy for a bucket.

Parameters for `set_bucket_policy`:

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.*