s3-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@s3-mcp list all objects in my 'user-uploads' bucket"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
S3 MCP Server
A Model Context Protocol (MCP) server for AWS S3 integration using FastMCP and boto3. This server provides access to S3 functionality through MCP-compatible tools.
Features
Bucket Management
list_buckets- Lists all S3 buckets in the AWS account.
Object Management
put_object- Puts an object into an S3 bucket.get_object- Gets an object from an S3 bucket.delete_object- Deletes an object from an S3 bucket.list_objects_v2- Lists objects in an S3 bucket.head_object- Retrieves metadata from an object without returning the object itself.upload_file- Uploads a file to an S3 object.download_file- Downloads an object from an S3 bucket to a file.copy_object- Copies an object from one S3 location to another.delete_objects- Deletes multiple objects from an S3 bucket.
Related MCP server: S3 MCP Server
Installation
Prerequisites
Python 3.10 or higher
uv package manager
AWS account with S3 access configured
Quick Start
Clone the repository:
git clone https://github.com/konstantinasm/s3-mcp.git cd s3-mcpInstall dependencies:
uv syncConfigure environment variables:
cp config/.env.example .env # Edit .env with your AWS credentials and S3 bucket detailsTest the installation:
uv run python scripts/test_server.py
Configuration
Required Environment Variables
AWS_ACCESS_KEY_ID- Your AWS Access Key IDAWS_SECRET_ACCESS_KEY- Your AWS Secret Access Key
Usage
Running the Server
With startup script (recommended):
uv run python scripts/start_server.pyDirect execution:
uv run python src/s3_mcp.pyTesting
Run test suite:
uv run python scripts/test_server.pyExample Tool Calls
List all S3 buckets:
list_buckets()MCP Integration
This server is designed to work with MCP-compatible clients. See MCP_SETUP.md for detailed integration instructions.
Docker Support
Using Docker Compose
Configure environment:
cp config/.env.example .env # Edit .env with your settingsRun with Docker Compose:
docker compose up -d
Building Docker Image
docker build -t s3-mcp-server .Development
Project Structure
s3-mcp/
├── src/
│ └── s3_mcp.py # Main server implementation
├── scripts/
│ ├── start_server.py # Startup script with validation
│ └── test_server.py # Test script
├── config/
│ ├── .env.example # Environment configuration template
│ └── mcp.json # MCP client configuration example
├── pyproject.toml # Python project configuration
├── requirements.txt # Dependencies
├── Dockerfile # Docker configuration
├── docker-compose.yml # Docker Compose setup
├── README.md # This file
├── MCP_SETUP.md # MCP integration guide
└── LICENSE # MIT licenseContributing
Contributions are welcome! If you have ideas, improvements, or bug fixes — feel free to submit a pull request.
How to Contribute:
Fork the repository.
Create a new branch for your changes.
Make your changes with clear, clean commits.
Open a pull request with a clear description of what you’ve done.
Please follow existing code style and keep commits focused. Questions or suggestions? Open an issue.
Running Tests
uv run python scripts/test_server.pyTroubleshooting
Common Issues
Permission Denied:
Verify AWS credentials have sufficient S3 permissions.
Check if read-only mode is enabled.
Tool Not Found:
Ensure all dependencies are installed:
uv sync.Verify Python version compatibility (3.10+).
Debug Mode
Set environment variable for detailed logging:
export DEBUG=1
uv run python scripts/start_server.pyDependencies
FastMCP - MCP server framework
boto3 - AWS SDK for Python
python-dotenv - Loads environment variables from a .env file
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
AWS S3 for cloud storage
Model Context Protocol for the integration standard
FastMCP for the server framework
Available Tools
10 toolscopy_objectA
Copies an object from one S3 location to another.
Args: source_bucket (str): The name of the source bucket. source_key (str): The key of the source object. destination_bucket (str): The name of the destination bucket. destination_key (str): The key of the destination object.
Returns: str: JSON formatted S3 response.
Inputs: source_bucket (required), source_key (required), destination_bucket (required), destination_key (required). Returns: result
delete_objectA
Deletes an object from an S3 bucket.
Args: bucket (str): The name of the bucket. key (str): The key (name) of the object.
Returns: str: JSON formatted S3 response.
Inputs: bucket (required), key (required). Returns: result
delete_objectsC
Deletes multiple objects from an S3 bucket.
Args: bucket (str): The name of the bucket. keys (List[str]): A list of keys to delete. quiet (bool): Suppress errors and return only failed deletions.
Returns: str: JSON formatted S3 response.
Inputs: bucket (required), keys (required), quiet. Returns: result
download_fileB
Downloads an object from an S3 bucket to a file.
Args: bucket (str): The name of the bucket to download from. key (str): The name of the key to download from. filename (str): The path to the file to download to.
Returns: str: JSON formatted success message.
Inputs: bucket (required), key (required), filename (required). Returns: result
get_objectC
Gets an object from an S3 bucket.
Args: bucket (str): The name of the bucket. key (str): The key (name) of the object.
Returns: str: JSON formatted S3 response.
Inputs: bucket (required), key (required). Returns: result
head_objectA
Retrieves metadata from an object without returning the object itself.
Args: bucket (str): The name of the bucket. key (str): The key (name) of the object. if_match (Optional[str]): Return object only if its ETag is the same. if_none_match (Optional[str]): Return object only if its ETag is different. version_id (Optional[str]): Version of the object.
Returns: str: JSON formatted S3 response.
Inputs: bucket (required), key (required), if_match, if_none_match, +1 more. Returns: result
list_bucketsA
Lists all buckets in the AWS account.
Returns: str: JSON formatted list of buckets.
Inputs: no named parameters. Returns: result
list_objects_v2B
Lists objects in an S3 bucket.
Args: bucket (str): The name of the bucket. prefix (Optional[str]): Filter for keys starting with this prefix. max_keys (Optional[int]): Maximum number of keys to return. continuation_token (Optional[str]): Token for paginating results. delimiter (Optional[str]): Delimiter for grouping keys.
Returns: str: JSON formatted S3 response.
Inputs: bucket (required), prefix, max_keys, continuation_token, +1 more. Returns: result
put_objectB
Puts an object into an S3 bucket.
Args: bucket (str): The name of the bucket. key (str): The key (name) of the object. body (str): The content of the object.
Returns: str: JSON formatted S3 response.
Inputs: bucket (required), key (required), body (required). Returns: result
upload_fileC
Uploads a file to an S3 object.
Args: filename (str): The path to the file to upload. bucket (str): The name of the bucket to upload to. key (str): The name of the key to upload to.
Returns: str: JSON formatted success message.
Inputs: filename (required), bucket (required), key (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Every tool has a clearly distinct purpose with no ambiguity. Each targets a specific S3 operation like copying, deleting, downloading, uploading, listing, or retrieving objects/buckets. The descriptions clearly differentiate between similar tools like delete_object vs delete_objects or get_object vs head_object.
All tools follow a consistent verb_noun naming pattern throughout (e.g., copy_object, delete_object, list_buckets). The naming is uniform with snake_case used consistently across all 10 tools, making them predictable and easy to understand.
With 10 tools, this server is well-scoped for S3 operations. Each tool earns its place by covering essential CRUD and management functions for S3 objects and buckets, from basic operations like put/get to advanced features like multi-object deletion and metadata retrieval.
The tool surface provides complete coverage for S3 object and bucket management. It includes all core CRUD operations (create/put, read/get/head/list, update via copy/replace, delete), plus specialized functions like multi-object deletion, file upload/download, and bucket listing, with no obvious gaps for the domain.
Maintenance
Related MCP Connectors
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
MCP server for the Seline Analytics API
Tigris MCP Server seamlessly connects AI agents to Tigris bucket and object management.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Related MCP Servers
- FlicenseBqualityDmaintenanceAn MCP server that provides tools for interacting with AWS S3 buckets, enabling direct access to S3 operations through the Model Context Protocol.1-
- AlicenseAqualityDmaintenanceAn 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.311,239 npm30MIT
- AlicenseAqualityDmaintenanceMCP server for AWS S3 — list buckets, browse objects, upload/download files, and generate presigned URLs.7106 npm4MIT
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that provides a bridge between MCP-compatible clients and MinIO object storage. It exposes MinIO operations as MCP tools for seamless bucket management and object operations.4-