S3

You can run an MCP server that lets large language models interact with Amazon S3 storage by listing buckets, listing objects, and retrieving object contents. This server exposes HTTP and STDIO transports so you can connect via web clients, local processes, or Claude Desktop, while keeping access restricted to configured buckets.

How to use

Choose a transport and connect your client. Use HTTP transport for web or REST-style interactions, or STDIO transport for direct process communication with Claude Desktop. The server provides an MCP endpoint for requests and an SSE stream for real-time responses. You can perform the following actions through your MCP client: list available buckets, list objects within a bucket, and fetch object contents.

How to install

Prerequisites you need before installing:
- Node.js 18 or higher
- npm or yarn
- Docker (optional, for containerized setup)
- AWS credentials configured (environment variables or AWS credentials file) for accessing S3 resources.

# Install globally via npm
npm install -g aws-s3-mcp

# Or add as a project dependency
npm install aws-s3-mcp

Configuration and startup options

Configure AWS credentials and S3 access by setting environment variables or creating a .env file. The server defaults to port 3000 for HTTP transport but you can customize as needed through environment variables.

# Example .env configuration
AWS_REGION=us-east-1
S3_BUCKETS=bucket1,bucket2,bucket3
S3_MAX_BUCKETS=5
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key

# Start the server with the default HTTP transport
npx aws-s3-mcp

HTTP transport startup example

When you run the server with HTTP transport, it starts on port 3000 by default and exposes key endpoints for health, MCP commands, and server-sent events.

# Start the server (HTTP transport by default)
npx aws-s3-mcp

# Health check
curl http://localhost:3000/health

# MCP endpoint
curl http://localhost:3000/mcp

# SSE endpoint
curl http://localhost:3000/sse

STDIO transport startup for Claude Desktop

To connect Claude Desktop directly, use STDIO transport. This requires starting the server in STDIO mode and configuring Claude to communicate with it via standard input and output.

{
  "mcpServers": {
    "s3": {
      "command": "npx",
      "args": ["aws-s3-mcp", "--stdio"],
      "env": {
        "AWS_REGION": "us-east-1",
        "S3_BUCKETS": "bucket1,bucket2,bucket3",
        "S3_MAX_BUCKETS": "5",
        "AWS_ACCESS_KEY_ID": "your-access-key",
        "AWS_SECRET_ACCESS_KEY": "your-secret-key"
      }
    }
  }
}

Docker and containerized setup

You can run the S3 MCP server inside Docker and, if you wish, pair it with MinIO for local testing. Use Docker CLI or Docker Compose to manage containers and networks.

# Build the Docker image
docker build -t aws-s3-mcp .

# Run with environment variables
docker run -d \
  -e AWS_REGION=us-east-1 \
  -e S3_BUCKETS=bucket1,bucket2 \
  -e S3_MAX_BUCKETS=5 \
  -e AWS_ACCESS_KEY_ID=your-access-key \
  -e AWS_SECRET_ACCESS_KEY=your-secret-key \
  --name aws-s3-mcp-server \
  aws-s3-mcp

# Docker Compose example (s3-mcp service)
docker compose up -d s3-mcp

Security considerations

The server will only access the buckets listed in the S3_BUCKETS configuration. AWS credentials must have permissions to those buckets. Apply the principle of least privilege and consider IAM roles for production deployments.

Notes on Claude Desktop integration

To use the server with Claude Desktop, prefer STDIO transport for direct interaction. You can also configure Claude Desktop to connect to a running Docker container if you start the container first and expose the MCP endpoint accordingly.

Troubleshooting and quick pointers

• Port conflicts: if port 3000 is in use, stop other services or change the port via environment configuration.
• Credentials: ensure AWS credentials are valid and have access to the specified buckets.
• Build issues: rebuild the Docker image if you modify dependencies.
• Endpoint checks: verify that health and MCP endpoints respond as expected.

Quick reference for connections

HTTP transport uses the MCP endpoint at http://localhost:3000/mcp with a health endpoint at /health and an SSE stream at /sse. STDIO transport connects via a running process using the node command shown in the STDIO configuration.

Available tools

list-buckets

Lists accessible S3 buckets, honoring configured bucket restrictions, with metadata like bucket creation date.

list-objects

Lists objects inside a specified bucket with optional prefix filtering and max results.

get-object

Retrieves the contents of a specified object from a bucket, returning text or binary data depending on the object type.