s3-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@s3-mcplist all objects in my 'user-uploads' bucket"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 MCP Server
Installation
Prerequisites
Python 3.10 or higher
uv package manager
AWS account with S3 access configured
Quick Start
Clone the repository:
git clone https://github.com/konstantinasm/s3-mcp.git cd s3-mcpInstall dependencies:
uv syncConfigure environment variables:
cp config/.env.example .env # Edit .env with your AWS credentials and S3 bucket detailsTest the installation:
uv run python scripts/test_server.py
Configuration
Required Environment Variables
AWS_ACCESS_KEY_ID- Your AWS Access Key IDAWS_SECRET_ACCESS_KEY- Your AWS Secret Access Key
Usage
Running the Server
With startup script (recommended):
uv run python scripts/start_server.pyDirect execution:
uv run python src/s3_mcp.pyTesting
Run test suite:
uv run python scripts/test_server.pyExample 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
Configure environment:
cp config/.env.example .env # Edit .env with your settingsRun 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 licenseContributing
Contributions are welcome! If you have ideas, improvements, or bug fixes — feel free to submit a pull request.
How to Contribute:
Fork the repository.
Create a new branch for your changes.
Make your changes with clear, clean commits.
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.pyTroubleshooting
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.pyDependencies
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
Available Tools
10 toolscopy_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.
| Name | Required | Description | Default |
|---|---|---|---|
| source_bucket | Yes | ||
| source_key | Yes | ||
| destination_bucket | Yes | ||
| destination_key | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| bucket | Yes | ||
| key | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| bucket | Yes | ||
| keys | Yes | ||
| quiet | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| bucket | Yes | ||
| key | Yes | ||
| filename | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| bucket | Yes | ||
| key | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| bucket | Yes | ||
| key | Yes | ||
| if_match | No | ||
| if_none_match | No | ||
| version_id | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| bucket | Yes | ||
| prefix | No | ||
| max_keys | No | ||
| continuation_token | No | ||
| delimiter | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| bucket | Yes | ||
| key | Yes | ||
| body | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| filename | Yes | ||
| bucket | Yes | ||
| key | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
10 tool updates
- First observed
copy_object - First observed
delete_object - First observed
delete_objects - First observed
download_file - First observed
get_object - First observed
head_object - First observed
list_buckets - First observed
list_objects_v2 - First observed
put_object - First observed
upload_file
TDQS
Scored across 10 tools
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.
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.
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.
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
Related MCP Connectors
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
A Model Context Protocol (MCP) server for Selise Blocks Cloud integration
MCP server for the Seline Analytics API
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Related MCP Servers
- FlicenseBqualityDmaintenanceAn MCP server that provides tools for interacting with AWS S3 buckets, enabling direct access to S3 operations through the Model Context Protocol.1-
- AlicenseAqualityFmaintenanceAn 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.3616 npm30MIT
- AlicenseAqualityDmaintenanceMCP server for AWS S3 — list buckets, browse objects, upload/download files, and generate presigned URLs.759 npm4MIT
- FlicenseNot gradedqualityDmaintenanceA 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-