Skip to main content
Glama
KonMam

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
source_bucketYes
source_keyYes
destination_bucketYes
destination_keyYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. While 'Copies' implies a read+write operation, it doesn't specify whether this overwrites existing destination objects, requires specific IAM permissions, has size/time limits, or provides progress feedback. The return format is mentioned but not the content or error conditions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is perfectly structured with a clear purpose statement followed by well-organized Args and Returns sections. Every sentence adds value: the first explains what the tool does, the Args section documents all parameters, and the Returns section specifies the output format. No wasted words or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-parameter S3 operation with no annotations, the description covers the basic operation and parameters adequately. The presence of an output schema means the description doesn't need to detail return values. However, as a mutation tool with security implications, it should address permissions, error conditions, and behavioral specifics more thoroughly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description provides essential parameter documentation through the Args section, clearly defining all 4 parameters with their types and purposes. However, it doesn't explain S3 key format conventions, bucket naming rules, or path semantics that would help users construct valid parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Copies') and resources involved ('object from one S3 location to another'), making the purpose immediately understandable. It distinguishes this tool from siblings like delete_object, get_object, and put_object by specifying it's a copy operation rather than deletion, retrieval, or creation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites like bucket permissions, whether the source must exist, or when to use copy_object versus download_file+upload_file combinations. There's no comparison to sibling tools like put_object for similar operations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
bucketYes
keyYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It states the action ('Deletes') and return format, but fails to mention critical aspects like permissions required, whether deletion is permanent/irreversible, error handling (e.g., for non-existent objects), or rate limits. For a destructive operation, this leaves significant gaps in understanding its behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with a clear purpose statement followed by Args and Returns sections. Every sentence adds value: the first defines the tool, and the subsequent lines explain inputs and outputs without redundancy. It's front-loaded and wastes no words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (destructive operation with 2 parameters), no annotations, but an output schema exists, the description is minimally adequate. It covers purpose and parameters but lacks behavioral details like safety warnings or error handling. The output schema mitigates the need to explain return values, but overall completeness is moderate with room for improvement.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explicitly documents both parameters ('bucket' and 'key') with brief explanations of their roles, adding meaningful context beyond the bare schema. However, it doesn't detail format constraints (e.g., bucket naming rules) or examples, keeping it somewhat basic but adequate given the low parameter count.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Deletes') and resource ('an object from an S3 bucket'), distinguishing it from siblings like 'delete_objects' (plural) and 'copy_object'/'get_object' which perform different operations. It precisely identifies what the tool does without ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'delete_objects' (for multiple objects) or other S3 operations. It lacks context about prerequisites, error conditions, or typical use cases, offering only basic functional information without comparative or exclusionary advice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
bucketYes
keysYes
quietNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden but offers minimal behavioral insight. It mentions that 'quiet' suppresses errors and returns only failed deletions, which is useful, but doesn't cover critical aspects like irreversible deletion, required permissions, rate limits, or response format details. For a destructive operation, this is inadequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear opening sentence followed by Args and Returns sections. It's front-loaded and avoids redundancy, though the 'Args' and 'Returns' labels are slightly verbose. Overall, it's efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a destructive tool with 3 parameters (0% schema coverage), no annotations, but an output schema, the description is moderately complete. It covers the basic purpose and some parameter behavior, but lacks safety warnings, permission requirements, and detailed usage context. The output schema helps, but key operational details are missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains 'quiet' parameter behavior clearly, adding value beyond the schema. However, it doesn't clarify 'bucket' (e.g., naming conventions) or 'keys' (e.g., format, wildcards), leaving gaps. The partial compensation justifies a baseline score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Deletes multiple objects') and resource ('from an S3 bucket'), making the purpose immediately understandable. It distinguishes from sibling 'delete_object' by specifying it handles multiple objects, though it doesn't explicitly contrast with other siblings like 'copy_object' or 'put_object'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., bucket existence, permissions), compare with 'delete_object' for single deletions, or advise on error handling with the 'quiet' parameter. The description lacks context for tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
bucketYes
keyYes
filenameYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action but doesn't mention permissions required (e.g., S3 read access), potential side effects (e.g., overwriting local files), error conditions (e.g., missing bucket/key), or performance aspects (e.g., file size limits). The return value is mentioned but lacks detail on error formats or success structure beyond 'JSON formatted success message'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear purpose statement followed by Args and Returns sections. It's front-loaded and wastes no words, though the 'Returns' section could be slightly more informative (e.g., noting what the JSON contains). Every sentence serves a purpose, making it efficient but not minimal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 3 parameters with 0% schema coverage and no annotations, the description adequately covers the basics but lacks depth for a file operation tool. It explains what the tool does and the parameters, but misses behavioral context (e.g., idempotency, error handling). The output schema exists, so describing return values isn't needed, but overall completeness is moderate due to the missing operational guidance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explicitly defines all three parameters with clear semantics: 'bucket' as the source bucket name, 'key' as the object key, and 'filename' as the local destination path. This adds essential meaning beyond the bare schema, though it doesn't specify format details (e.g., path conventions or key patterns).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Downloads an object from an S3 bucket to a file') with the exact resource (S3 object). It distinguishes from siblings like 'get_object' (which might retrieve metadata) and 'upload_file' (which does the opposite). The verb+resource combination is precise and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'get_object' (which might return the object content differently) or 'copy_object' (which copies within S3). It mentions no prerequisites, exclusions, or contextual triggers, leaving the agent to infer usage from the tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
bucketYes
keyYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('Gets') and return format ('JSON formatted S3 response'), but doesn't mention critical details like authentication requirements, error handling, rate limits, or whether it retrieves metadata or full content. This is a significant gap for a tool interacting with external storage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and concise, with a clear purpose statement followed by Args and Returns sections. Each sentence serves a purpose, and there's no redundant information. It could be slightly more front-loaded by integrating the return format into the main sentence, but overall it's efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (external S3 interaction) and lack of annotations, the description is minimally adequate. It covers the basic action and parameters but misses important behavioral context. The presence of an output schema means the description doesn't need to detail return values, but it should still address usage and error scenarios more thoroughly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the schema provides no parameter descriptions. The description adds basic semantics by explaining 'bucket' as 'The name of the bucket' and 'key' as 'The key (name) of the object', which clarifies what these parameters represent. However, it doesn't provide examples, constraints, or format details, leaving room for ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Gets') and resource ('an object from an S3 bucket'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'head_object' or 'download_file', which might retrieve object metadata or download content differently.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives such as 'head_object' for metadata or 'download_file' for file downloads. It lacks any context about prerequisites, error conditions, or typical use cases, leaving the agent to infer usage from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
bucketYes
keyYes
if_matchNo
if_none_matchNo
version_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It clearly states this is a read operation ('Retrieves'), which is helpful. However, it doesn't mention authentication requirements, rate limits, error conditions, or what specific metadata is returned. The description adds basic behavioral context but lacks important operational details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (purpose, Args, Returns). The opening sentence efficiently states the core purpose. The parameter explanations are concise but informative. There's minimal wasted text, though the Returns section could be slightly more detailed given the output schema exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only metadata retrieval tool with 5 parameters and an output schema, the description is reasonably complete. It explains all parameters and states the return format. However, it could better explain what 'metadata' includes and mention common use cases. The existence of an output schema reduces the need to detail return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must compensate. It provides clear explanations for all 5 parameters in the Args section, adding meaningful context beyond the bare schema. The explanations for if_match, if_none_match, and version_id are particularly valuable. However, it doesn't explain parameter formats or constraints (e.g., bucket naming rules).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Retrieves metadata') and resource ('from an object'), distinguishing it from siblings like get_object (which returns the object content) and copy_object/delete_object (which modify objects). The phrase 'without returning the object itself' explicitly differentiates it from get_object.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context about when to use this tool ('Retrieves metadata from an object without returning the object itself'), which implicitly suggests using get_object when you need the actual content. However, it doesn't explicitly name alternatives or state when NOT to use this tool, keeping it at a 4 rather than a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_bucketsA

Lists all buckets in the AWS account.

Returns: str: JSON formatted list of buckets.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. While it states the return format ('JSON formatted list of buckets'), it lacks critical behavioral context such as authentication requirements, rate limits, pagination behavior, error conditions, or whether this operation is safe/read-only. The description doesn't contradict annotations (none exist), but provides minimal behavioral insight.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured in two sentences: first stating the core functionality, then specifying the return format. Every sentence adds value, with no redundant information. It could be slightly improved by front-loading the return format information more explicitly, but overall it's appropriately concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, has output schema) and lack of annotations, the description provides basic but incomplete context. It covers what the tool does and the return format, but misses important operational details like authentication, error handling, and behavioral characteristics that would be crucial for an agent to use this AWS tool effectively. The existence of an output schema reduces the need to describe return values, but other gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so there are no parameter semantics to explain. The description appropriately doesn't attempt to describe non-existent parameters. With 100% schema description coverage (empty schema) and no parameters, a baseline score of 4 is appropriate as there's nothing missing or misleading about parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Lists') and resource ('all buckets in the AWS account'), making the purpose immediately understandable. It distinguishes this tool from siblings like list_objects_v2 (which lists objects within a bucket) by focusing on bucket-level enumeration rather than object-level operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context by specifying 'AWS account' scope, but provides no explicit guidance on when to use this versus alternatives like list_objects_v2 or other bucket-related operations. There's no mention of prerequisites, permissions needed, or comparison with sibling tools beyond the inherent resource distinction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
bucketYes
prefixNo
max_keysNo
continuation_tokenNo
delimiterNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the return format ('JSON formatted S3 response') which is helpful, but doesn't describe pagination behavior, rate limits, permissions required, error conditions, or whether this is a read-only operation. For an S3 listing tool with 5 parameters, this leaves significant behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is perfectly structured and concise: a clear purpose statement followed by well-organized Args and Returns sections. Every sentence earns its place, with no redundant information. The formatting makes it easy to scan and understand.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (5 parameters, S3 operations) and the presence of an output schema (implied by 'Returns: str: JSON formatted S3 response'), the description is moderately complete. It covers all parameters well but lacks behavioral context about pagination, permissions, and error handling. With no annotations and siblings that include destructive operations, more guidance would be helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must compensate - and it does well by explaining all 5 parameters with clear semantics: bucket as the container, prefix for filtering, max_keys for limiting results, continuation_token for pagination, and delimiter for grouping. This adds substantial value beyond the bare schema. The only minor gap is not explaining format expectations for continuation_token.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Lists' and resource 'objects in an S3 bucket', making the purpose immediately understandable. It distinguishes from siblings like list_buckets (which lists buckets rather than objects) and other object operations like get_object or delete_object. However, it doesn't explicitly contrast with all siblings, so it's not a perfect 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when list_objects_v2 is preferred over list_buckets (for listing objects vs buckets) or when pagination via continuation_token should be used. There's no discussion of prerequisites, performance considerations, or typical use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
bucketYes
keyYes
bodyYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. While it mentions the action ('Puts') and return format ('JSON formatted S3 response'), it lacks critical details: whether this requires specific permissions, what happens if the object already exists (overwrites?), any rate limits, error conditions, or authentication requirements. For a write operation to cloud storage, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with a clear purpose statement followed by well-organized Args and Returns sections. Every sentence earns its place by providing essential information without redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that this is a write operation with no annotations and 3 parameters, the description does an adequate job covering the basics: purpose, parameters, and return format. However, it lacks important context about behavioral traits (overwrite behavior, permissions, errors) and doesn't help differentiate from sibling tools. The presence of an output schema reduces the need to explain return values in detail.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description explicitly documents all three parameters (bucket, key, body) with clear semantic explanations beyond the schema's basic titles. Since schema description coverage is 0%, this documentation is essential and adds substantial value by explaining what each parameter represents (e.g., 'key' as 'the name of the object').

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Puts an object') and resource ('into an S3 bucket'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'upload_file' or 'copy_object', which could create ambiguity about when to use this specific tool versus alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'upload_file' or 'copy_object'. It doesn't mention prerequisites, constraints, or typical use cases, leaving the agent to guess based on tool names alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
filenameYes
bucketYes
keyYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the action ('Uploads') and return type, but fails to cover critical aspects like authentication requirements, error handling, file size limits, or overwrite behavior. This leaves significant gaps in understanding how the tool behaves in practice.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear purpose statement followed by Args and Returns sections. It is front-loaded and efficient, with no redundant sentences, though the parameter explanations could be more detailed without sacrificing brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (file upload to S3), no annotations, and an output schema that only specifies a string return, the description is moderately complete. It covers the basic operation and parameters but misses important contextual details like error cases, performance considerations, or integration with sibling tools, leaving room for improvement.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It lists all three parameters with brief explanations, adding basic semantics beyond the schema's titles. However, it lacks details on formats (e.g., path conventions for 'filename', S3 naming rules for 'key') or constraints, providing only minimal enhancement.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Uploads a file') and target resource ('to an S3 object'), making the purpose unambiguous. However, it does not explicitly differentiate from sibling tools like 'put_object' or 'copy_object', which might have overlapping functionality in S3 contexts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as 'put_object' or 'copy_object'. The description lacks context about prerequisites, constraints, or typical use cases, leaving the agent without explicit usage instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 10 tool updates
    • First observedcopy_object
    • First observeddelete_object
    • First observeddelete_objects
    • First observeddownload_file
    • First observedget_object
    • First observedhead_object
    • First observedlist_buckets
    • First observedlist_objects_v2
    • First observedput_object
    • First observedupload_file

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
ResponsivenessNo issues

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
    F
    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
    616 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
    -