Skip to main content
Glama
s3-mcp

s3-mcp

by KonMam

S3 MCP Server

License: MIT Python 3.10+

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

  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

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Available Tools

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

    A3.7/5.0

    Scored across 10 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      D
      maintenance
      An MCP server that provides tools for interacting with AWS S3 buckets, enabling direct access to S3 operations through the Model Context Protocol.
      1
      -
    • A
      license
      A
      quality
      D
      maintenance
      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.
      3
      11,239 npm
      30
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A 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
      -