home / mcp / s3 mcp server

S3 MCP Server

Provides MCP-based access to AWS S3 operations including buckets and object management via FastMCP and boto3.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "konmam-s3-mcp": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "src/s3_mcp.py"
      ],
      "env": {
        "AWS_ACCESS_KEY_ID": "YOUR_AWS_ACCESS_KEY_ID",
        "AWS_SECRET_ACCESS_KEY": "YOUR_AWS_SECRET_ACCESS_KEY"
      }
    }
  }
}

You get an MCP server that exposes AWS S3 capabilities through a Model Context Protocol interface. This lets MCP-compatible clients perform common S3 operations against your AWS account from a unified, tool-agnostic workflow.

How to use

Run the MCP server locally or in a container, then connect your MCP client to perform S3 actions. You’ll call distinct functions for each operation, such as listing buckets or manipulating objects, and the server will relay those requests to your configured AWS account. Ensure your AWS credentials are configured so the server can access S3 resources.

How to install

Prerequisites: Python 3.10 or higher, and the uv package manager. You also need an AWS account with S3 access configured.

1. Clone the project and move into the directory.

git clone https://github.com/konstantinasm/s3-mcp.git
cd s3-mcp

2. Install dependencies using the uv command line tool.

uv sync

3. Configure environment variables for AWS access. Create a .env file or edit the existing example.

cp config/.env.example .env
# Edit .env to include AWS credentials and S3 settings

4. Start the server. Use the startup script or run the main module directly.

uv run python scripts/start_server.py
# Or start directly
uv run python src/s3_mcp.py

5. Run tests to verify the setup.

uv run python scripts/test_server.py

Additional sections

Configuration details for AWS access are required to enable S3 operations. Provide your AWS Access Key ID and AWS Secret Access Key, and ensure the AWS account has permissions for the S3 actions you intend to use.

Configuration

Required environment variables include the following:

- AWS_ACCESS_KEY_ID – Your AWS Access Key ID (required)

- AWS_SECRET_ACCESS_KEY – Your AWS Secret Access Key (required)

Testing and tooling

Test the server locally to ensure S3 endpoints operate as expected before integrating with your MCP clients.

MCP Integration

This server is designed to work with MCP-compatible clients. When you configure an MCP client, point it at the running server and enable the S3 operations you need. Use the client’s MCP interface to invoke functions such as list_buckets, put_object, get_object, and delete_object.

Docker and development

Docker can be used to run the server in a container. Follow the steps in the project setup to configure environment variables, then start the container with Docker Compose.

Troubleshooting

Common issues include missing AWS permissions or credentials. Verify that your credentials have optimal S3 permissions and that your environment variables are loaded correctly. If the tool cannot be located, ensure all dependencies are installed with the uv sync command.

For detailed logs, enable debug mode by setting DEBUG=1 and starting the server again.

Available tools

list_buckets

Lists all S3 buckets in the AWS account.

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.