s3-mcp

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.

Installation

Prerequisites

• Python 3.10 or higher
• uv package manager
• AWS account with S3 access configured

Quick Start

1. Clone the repository:
   git clone https://github.com/konstantinasm/s3-mcp.git cd s3-mcp
2. Install dependencies:
   uv sync
3. Configure environment variables:
   cp config/.env.example .env # Edit .env with your AWS credentials and S3 bucket details
4. Test the installation:
   uv run python scripts/test_server.py

Configuration

Required Environment Variables

• AWS_ACCESS_KEY_ID - Your AWS Access Key ID
• AWS_SECRET_ACCESS_KEY - Your AWS Secret Access Key

Usage

Running the Server

With startup script (recommended):

Direct execution:

Testing

Run test suite:

Example Tool Calls

List all S3 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

1. Configure environment:
   cp config/.env.example .env # Edit .env with your settings
2. Run with Docker Compose:
   docker compose up -d

Building Docker Image

Development

Project Structure

Contributing

Contributions are welcome! If you have ideas, improvements, or bug fixes — feel free to submit a pull request.

How to Contribute:

1. Fork the repository.
2. Create a new branch for your changes.
3. Make your changes with clear, clean commits.
4. 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

Troubleshooting

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:

Dependencies

• 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