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-tools

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):

uv run python scripts/start_server.py

Direct execution:

uv run python src/s3_mcp.py

Testing

Run test suite:

uv run python scripts/test_server.py

Example 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

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

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 license

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

uv run python scripts/test_server.py

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:

export DEBUG=1
uv run python scripts/start_server.py

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