This MCP server provides a standardized interface for AI models to securely interact with AWS S3. It exposes capabilities to list S3 buckets, list objects within a bucket, and download the contents of specific objects. The server is designed to work within the Model Context Protocol ecosystem, enabling seamless requests from LLMs or AI apps to query bucket metadata, browse object listings, and fetch file data for downstream processing. To start, ensure AWS credentials are configured and accessible to the server process. Then run the server and expose the MCP endpoints that models can call via the MCP protocol.

Once running, you can integrate the MCP S3 server with your AI workflow by issuing MCP-style requests to list buckets, retrieve objects in a bucket, or download file contents. This enables data discovery and retrieval within AI prompts, enabling tasks such as data analysis, document processing, and automated retrieval of PDFs or other files from S3 for model-driven workflows.

Prerequisites:

• Python 3.10 or higher
• AWS credentials configured (via ~/.aws/credentials, environment variables, or IAM roles)
• Optional but recommended: uv package manager for Python installations

Option A: Install as a Python package (recommended for MCP workflows)

1. Install uv (optional, recommended): curl -LsSf https://astral.sh/uv/install.sh | sh # Unix/macOS

   or Windows: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Install the MCP S3 server package from PyPI: pip install mcp-s3-server
3. Run the MCP S3 server: python -m mcp_s3_server

Option B: Development installation (from source)

1. Clone the repository: git clone https://github.com/ENGRZULQARNAIN/mcp_s3_server.git cd mcp_s3_server
2. Install with uv (recommended) or via pip in editable mode: uv sync

   or

   pip install -e .
3. Run the MCP S3 server: python -m mcp_s3_server

Configuration:

• Ensure AWS credentials are accessible to the process (environment variables, credentials file, or IAM roles).
• The server will use the configured AWS account to list buckets, list objects, and fetch file contents.

Tips and considerations:

• If you encounter AWS permission errors, verify that the credentials have permissions for s3:ListBuckets, s3:ListObjectsV2, and s3:GetObject.
• You may want to cap the number of objects returned by listing operations if applicable in your MCP deployment. Adjust AWS API query parameters accordingly if supported by your setup.
• For large buckets or large objects, consider streaming downloads or handling pagination as needed in your client application.
• Environment variables: ensure AWS_DEFAULT_REGION is set; avoid embedding credentials in code. Use roles or credentials files where possible.
• If running behind a firewall or in restricted environments, ensure outgoing access to AWS S3 endpoints is allowed.