The S3 MCP Server enables interaction with AWS S3 storage through Large Language Models (LLMs) like Claude, providing tools for:
- List available S3 buckets: Retrieve accessible buckets within configuration limits
- List objects in a bucket: View objects in a specified bucket, with optional prefix filtering and result limits
- Retrieve object contents: Access text files directly or get limited details for binary files
- Secure access control: Restricts access based on permissions and configurable bucket limitations
- Claude Desktop integration: Works with Claude Desktop via Docker or Node.js
- Local testing: Supports MinIO for development with pre-configured test environments
This server serves as a bridge between LLMs and S3 storage for programmatic management of cloud storage resources.
Provides tools for listing available S3 buckets, listing objects within a bucket, and retrieving object contents from AWS S3 storage.
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
- Install via npm:
- If building from source:
- Configure AWS credentials and S3 access:
Create a .env
file with your AWS configuration:
Or set these as environment variables.
Configuration
The server can be configured using the following environment variables:
Variable | Description | Default |
---|---|---|
AWS_REGION | AWS region where your S3 buckets are located | us-east-1 |
S3_BUCKETS | Comma-separated list of allowed S3 bucket names | (empty) |
S3_MAX_BUCKETS | Maximum number of buckets to return in listing | 5 |
AWS_ACCESS_KEY_ID | AWS access key (if not using default credentials) | (from AWS config) |
AWS_SECRET_ACCESS_KEY | AWS secret key (if not using default credentials) | (from AWS config) |
Running the Server
Direct Node.js Execution
The server runs with HTTP transport by default, making it easy to test and debug:
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
- Build the Docker image:
- Run the container with environment variables:
- Check container logs:
- Stop and remove the container:
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
- Build and start the Docker container:
- To stop the container:
Using Docker with MinIO for Testing
The Docker Compose setup includes a MinIO service for local testing:
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
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)
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
- Health check:
2. Local Development (STDIO)
This mode directly connects the MCP Inspector to the server process using standard input/output.
3. Docker with Real AWS (STDIO)
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)
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)
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
Debugging Tips
- Check container logs:
- Test endpoints manually:
- Access MinIO Web UI (Docker Compose only):
- URL:
http://localhost:9001
- Username:
minioadmin
- Password:
minioadmin
- URL:
Cleanup
Troubleshooting
- Port conflicts: If port 3000 is in use, stop other services or change the port
- AWS credentials: Ensure your
.env
file has valid AWS credentials for Docker modes - Build errors: Use
--force-rebuild
to rebuild Docker images - Connection issues: Check that containers are running with
docker ps
Quick Reference
Command | Transport | Environment | Description |
---|---|---|---|
./run-inspector.sh | HTTP | Local | Local development with HTTP transport |
./run-inspector.sh --stdio | STDIO | Local | Local development with STDIO transport |
./run-inspector.sh --docker | STDIO | Docker + AWS | Docker container with AWS credentials |
./run-inspector.sh --docker --http | HTTP | Docker + AWS | Docker container with HTTP transport |
./run-inspector.sh --docker-compose | STDIO | Docker + MinIO | Local testing with MinIO (no AWS needed) |
Connecting to Claude Desktop
To use this server with Claude Desktop, you'll need to use STDIO transport (not the default HTTP transport) for direct process communication:
- Edit your Claude Desktop configuration file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
- Add the S3 MCP server to the configuration:
Docker Option for Claude Desktop 🐳
You can also configure Claude Desktop to use a running Docker container for the MCP server:
⚠️ Important Prerequisites: For this Docker configuration to work, you MUST first build and run the Docker container BEFORE launching Claude Desktop:
Without a running container, Claude Desktop will show errors when trying to use S3 tools.
The Docker configuration above uses
exec
to send MCP requests directly to the running container. No port mapping is required since Claude communicates directly with the container instead of through a network port.
Note: Ensure the container name in the configuration (
aws-s3-mcp-server
) matches the name of your running container.
Important: Please note the following when using the configuration above
- Replace
AWS_ACCESS_KEY_ID
andAWS_SECRET_ACCESS_KEY
with your actual credentialsS3_BUCKETS
should contain a comma-separated list of buckets you want to allow access toAWS_REGION
should be set to the region where your buckets are located
💣 If error occurs on Claude Desktop
If you encounter errors with the above configuration in Claude Desktop, try using absolute paths as follows:
Available Tools
list-buckets
Lists available S3 buckets that the server has permission to access. This tool respects the S3_BUCKETS
configuration that limits which buckets are shown.
Parameters: None
Example output:
list-objects
Lists objects in a specified S3 bucket.
Parameters:
bucket
(required): Name of the S3 bucket to list objects fromprefix
(optional): Prefix to filter objects (like a folder path)maxKeys
(optional): Maximum number of objects to return
Example output:
get-object
Retrieves an object from a specified S3 bucket. Text files are returned as plain text, while binary files are returned with limited details.
Parameters:
bucket
(required): Name of the S3 bucketkey
(required): Key (path) of the object to retrieve
Example text output:
Example binary output:
Security Considerations
- The server will only access buckets specified in the
S3_BUCKETS
environment variable - AWS credentials must have appropriate permissions to the buckets
- Use the principle of least privilege when configuring AWS permissions
- For production use, consider using IAM roles with specific S3 permissions
Usage with Claude
When interacting with Claude in the desktop app, you can ask it to perform S3 operations like:
- "List all my S3 buckets"
- "Summarize PDF files in my-documents-bucket"
- "Get the README.txt file from my-documents-bucket"
Claude will use the appropriate MCP tool to carry out the request and show you the results.
License
MIT
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
An Amazon S3 Model Context Protocol server that allows Large Language Models like Claude to interact with AWS S3 storage, providing tools for listing buckets, listing objects, and retrieving object contents.
Related MCP Servers
- AsecurityAlicenseAqualityA Model Context Protocol server that enables Claude to execute Python code using boto3 to query and manage AWS resources directly from conversations.Last updated -119PythonMIT License
- AsecurityAlicenseAqualityA Model Context Protocol server implementation that enables Claude to perform AWS operations on S3 and DynamoDB services through natural language commands.Last updated -23125PythonMIT License
- AsecurityFlicenseAqualityA Model Context Protocol server allowing Claude AI to interact with AWS resources through natural language, enabling users to query and manage AWS services without using the traditional AWS Console or CLI.Last updated -34TypeScript
- -securityAlicense-qualityA Model Context Protocol server that enables Large Language Models like Claude to manage Linode cloud resources, including listing regions, creating, viewing, deleting, and rebooting Linode instances.Last updated -1PythonMIT License