S3 MCP Server

An Amazon S3 Model Context Protocol (MCP) server that provides tools for interacting with S3 buckets and objects.

https://github.com/user-attachments/assets/d05ff0f1-e2bf-43b9-8d0c-82605abfb666

Features

🚀 MCP Transport Support

• ✅ STDIO Transport - Direct process communication for Claude Desktop
• ✅ HTTP Transport - REST API with Server-Sent Events for web clients
• ✅ Streamable HTTP - Real-time streaming for responsive interactions

🛠️ Available Tools

• ✅ list-buckets - List accessible S3 buckets with filtering
• ✅ list-objects - Browse objects within buckets with prefix filtering
• ✅ get-object - Retrieve object contents (text/binary support)

🐳 Deployment Options

• ✅ Local Node.js - Direct execution with npm/node
• ✅ Docker CLI - Containerized deployment with custom configuration
• ✅ Docker Compose - Full stack with MinIO for local testing
• ✅ MCP Inspector - Built-in debugging and testing interface

Overview

This MCP server allows Large Language Models (LLMs) like Claude to interact with AWS S3 storage. It provides tools for:

• Listing available S3 buckets
• Listing objects within a bucket
• Retrieving object contents

The server is built using TypeScript and the MCP SDK, providing a secure and standardized way for LLMs to interface with S3.

Installation

Prerequisites

• Node.js 18 or higher
• npm or yarn
• AWS credentials configured (either through environment variables or AWS credentials file)
• Docker (optional, for containerized setup)

Setup

1. Install via npm:

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

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

1. If building from source:

# Clone the repository
git clone https://github.com/samuraikun/aws-s3-mcp.git
cd aws-s3-mcp

# Install dependencies and build
npm install
npm run build

1. Configure AWS credentials and S3 access:

Create a .env file with your AWS 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

Or set these as environment variables.

Configuration

The server can be configured using the following environment variables:

Running the Server

Direct Node.js Execution

The server runs with HTTP transport by default, making it easy to test and debug:

# Using npx (HTTP transport by default)
npx aws-s3-mcp

# If installed globally (HTTP transport)
npm install -g aws-s3-mcp
aws-s3-mcp

# If running from cloned repository (HTTP transport)
npm start

# Or directly (HTTP transport)
node dist/index.js

# Explicit HTTP transport
node dist/index.js --http

# STDIO transport (for Claude Desktop integration)
node dist/index.js --stdio

When running with HTTP transport (default), the server will start on port 3000 and provide:

• Health check endpoint: http://localhost:3000/health
• MCP endpoint: http://localhost:3000/mcp
• SSE endpoint: http://localhost:3000/sse

Docker Setup 🐳

You can run the S3 MCP server as a Docker container using either Docker CLI or Docker Compose.

Using Docker CLI

1. Build the Docker image:

docker build -t aws-s3-mcp .

1. Run the container with environment variables:

# Option 1: Pass environment variables directly
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

# Option 2: Use environment variables from .env file
docker run -d \
  --env-file .env \
  --name aws-s3-mcp-server \
  aws-s3-mcp

1. Check container logs:

docker logs aws-s3-mcp-server

1. Stop and remove the container:

docker stop aws-s3-mcp-server
docker rm aws-s3-mcp-server

Note: For HTTP transport (default), add -p 3000:3000 to expose the HTTP port. For STDIO transport (Claude Desktop), no port mapping is needed as it uses Docker exec for direct communication.

Using Docker Compose

1. Build and start the Docker container:

# Build and start the container
docker compose up -d s3-mcp

# View logs
docker compose logs -f s3-mcp

1. To stop the container:

docker compose down

Using Docker with MinIO for Testing

The Docker Compose setup includes a MinIO service for local testing:

# Start MinIO and the MCP server
docker compose up -d

# Access MinIO console at http://localhost:9001
# Default credentials: minioadmin/minioadmin

The MinIO service automatically creates two test buckets (test-bucket-1 and test-bucket-2) and uploads sample files for testing.

Debugging with MCP Inspector 🔍

The run-inspector.sh script provides an easy way to test and debug the S3 MCP server using the MCP Inspector. It supports multiple transport types and deployment modes.

Quick Start

# Show all available options
./run-inspector.sh --help

# Run locally with HTTP transport (default)
./run-inspector.sh

# Run with Docker Compose and MinIO for testing
./run-inspector.sh --docker-compose

Transport Types

The server supports two transport protocols:

HTTP Transport

• Best for: Web-based debugging, external client connections
• Provides: REST API endpoints, Server-Sent Events (SSE)
• Ports: 3000 (HTTP), 3001+ (Inspector UI)

STDIO Transport

• Best for: Direct process communication, Claude Desktop integration
• Provides: Standard input/output communication
• Ports: None (direct process communication)

Usage Examples

1. Local Development (HTTP)

# Default: HTTP transport for local debugging
./run-inspector.sh

# Explicit HTTP transport
./run-inspector.sh --http

This will:

• Build the project if needed
• Start the MCP server with HTTP transport on port 3000
• Launch MCP Inspector in your browser
• Provide endpoints:
  • Health check: http://localhost:3000/health
  • MCP endpoint: http://localhost:3000/mcp
  • SSE endpoint: http://localhost:3000/sse

2. Local Development (STDIO)

# STDIO transport for local debugging
./run-inspector.sh --stdio

This mode directly connects the MCP Inspector to the server process using standard input/output.

3. Docker with Real AWS (STDIO)

# Create .env file with your AWS credentials
cp .env.example .env
# Edit .env with your AWS credentials

# Run with Docker using STDIO transport (default for Docker)
./run-inspector.sh --docker

This will:

• Build the Docker image if needed
• Start a container with your AWS credentials
• Connect MCP Inspector via Docker exec

4. Docker with Real AWS (HTTP)

# Run with Docker using HTTP transport
./run-inspector.sh --docker --http

This will:

• Start a containerized HTTP server on port 3000
• Connect MCP Inspector to the HTTP endpoint
• Useful for testing HTTP-based integrations

5. Docker Compose with MinIO (Testing)

# Run with MinIO for local testing (no AWS credentials needed)
./run-inspector.sh --docker-compose

This will:

• Start MinIO S3-compatible storage
• Create test buckets: test-bucket-1, test-bucket-2
• Upload sample files for testing
• Start the S3 MCP server connected to MinIO
• Launch MCP Inspector
• Provide MinIO Web UI at http://localhost:9001 (login: minioadmin/minioadmin)

Advanced Options

Force Rebuild

# Force Docker image rebuild
./run-inspector.sh --docker --force-rebuild
./run-inspector.sh --docker-compose --force-rebuild

Debugging Tips

1. Check container logs:

   # For Docker CLI mode
   docker logs aws-s3-mcp-server
   
   # For Docker Compose mode
   docker compose logs s3-mcp
   

2. Test endpoints manually:

   # Health check
   curl http://localhost:3000/health
   
   # MinIO health (Docker Compose)
   curl http://localhost:9000/minio/health/live
   

3. Access MinIO Web UI (Docker Compose only):

   • URL: http://localhost:9001
   • Username: minioadmin
   • Password: minioadmin

Cleanup

# Stop and remove Docker containers
docker stop aws-s3-mcp-server && docker rm aws-s3-mcp-server

# Stop Docker Compose services
docker compose down

# St

---