Skip to main content
Glama
ENGRZULQARNAIN

mcp-s3-server

by ENGRZULQARNAIN
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Model Context Protocol (MCP) Server for AWS S3

This repository provides an implementation of a Model Context Protocol (MCP) server for AWS S3, enabling AI models, particularly Large Language Models (LLMs), to securely interact with S3 buckets. The server offers a standardized interface to list S3 buckets, list objects within buckets, and download file contents. It facilitates seamless integration between AI applications and AWS S3 storage for efficient data retrieval and management.

Key Features

  • List S3 Buckets: Retrieve a list of available buckets in an AWS account.

  • List Objects: Display objects within a specified bucket.

  • File Download: Fetch the contents of specific objects, such as documents or other files.

  • Secure Interaction: Provides a standardized, secure interface for AI models to interact with S3.

  • MCP Ecosystem: Part of the Model Context Protocol ecosystem, supporting AI model integration with various data sources.

Use Cases

  • Data Analysis: Access and analyze data stored in S3 buckets for AI-driven applications.

  • Document Retrieval: Retrieve specific files (e.g., PDFs) for processing by AI models.

  • Automation: Automate S3 bucket management tasks via natural language queries with LLMs.

  • AI Development: Support development of AI models requiring access to external data sources.

Prerequisites

To use this server, developers need:

  • Python 3.10 or higher

  • Configured AWS credentials (Access Key ID, Secret Access Key, and Region)

  • uv package manager (recommended) or pip

  • Familiarity with the Model Context Protocol for AI application integration

Limitations

Some implementations may:

  • Support only specific file types (e.g., PDFs in certain versions).

  • Have limits on the number of retrieved objects (e.g., up to 1000 objects).

  • Require specific configurations, such as the maximum number of buckets to return.

Installation and Usage

Option 1: Install from PyPI (Recommended)

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh  # Unix/macOS
# or for Windows: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Install the MCP S3 server
uv add mcp-s3-server

# Or using pip
pip install mcp-s3-server

Option 2: Development Installation

# Clone the repository
git clone https://github.com/ENGRZULQARNAIN/mcp_s3_server.git
cd mcp_s3_server

# Install with uv (recommended)
uv sync

# Or install with pip
pip install -e .

Configuration and Usage

  1. Configure AWS credentials using one of these methods:

    • AWS credentials file (~/.aws/credentials)

    • Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION)

    • IAM roles (for EC2 instances)

  2. Start the server:

    mcp-s3-server

  3. Integrate with an AI model or application using the MCP interface.

Refer to the repository's documentation for detailed setup instructions and API usage.

Contributing

Contributions are welcome! Please read the CONTRIBUTING.md file for guidelines on submitting issues, feature requests, or pull requests.

License

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

Available Tools

2 tools
list_s3_bucketsA

List all S3 buckets in your storage account (supports AWS S3, DigitalOcean Spaces, IBM Cloud Object Storage, and other S3-compatible services)

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.9/5.0
Behavior2/5

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

No annotations provided, so description bears full burden. It does not disclose behavior like pagination, rate limits, permission requirements, or response format. For a simple list operation, this is a notable 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?

Single sentence, front-loaded with the primary action, no wasted 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 no parameters and no output schema, the description is mostly adequate but does not explain the return format or any limits. For a read-only list tool, some behavioral cues would strengthen completeness.

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?

Input schema has zero parameters with 100% schema coverage, so baseline is 4. Description adds no parameter information as none exist, but that is acceptable.

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?

Description clearly states the verb 'List' and the resource 'S3 buckets', with explicit scope ('in your storage account') and support for multiple S3-compatible services. It distinguishes from sibling tool 'test_connection' which is for connectivity testing.

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?

Implies usage: when you need to list all S3 buckets. No explicit when-not or alternatives, but the single sibling (test_connection) provides natural context. Could mention that this tool does not filter or test connectivity.

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

test_connectionC

Test MCP S3 server connection

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

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 alone must convey behavior. It only says 'Test connection' without explaining what that entails (e.g., network call, credential verification).

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

Conciseness3/5

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

The description is very short and front-loaded, but it omits necessary details for a tool with no annotations or output schema, making it under-specified.

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

Completeness2/5

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

For a tool with no parameters and no output schema, the description should clarify what 'test' means and what the outcome is (e.g., success/failure). It does not provide this, leaving the agent underinformed.

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 parameters and 100% schema coverage, the baseline is 4. The description adds no parameter-specific information but is consistent with the empty schema.

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 tool tests the MCP S3 server connection, distinguishing it from the sibling tool list_s3_buckets. However, it lacks specificity about what aspect of the connection is tested.

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 on when to use this tool versus list_s3_buckets or other alternatives. The description simply states the action without context.

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. 2 tool updatesv0.1.3
    • First observedlist_s3_buckets
    • First observedtest_connection
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: listing buckets vs. testing connection. No overlap exists.

Naming Consistency5/5

Both tools use a consistent verb_noun pattern in snake_case (list_s3_buckets, test_connection).

Tool Count2/5

With only 2 tools for an S3 server, the set feels too thin. Typical S3 services require many more operations (e.g., object CRUD, bucket management).

Completeness1/5

The server lacks essential S3 operations such as listing objects, uploading/downloading files, and creating/deleting buckets, making the tool surface severely incomplete.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers