AWS S3 Configuration
Relevant source files
The following files were used as context for generating this wiki page:
The AWS S3 configuration system provides a centralized mechanism for managing environment variables, credentials, and operational constraints for the aws-s3-mcp server. It ensures that the Model Context Protocol (MCP) server can securely interact with Amazon S3 storage by validating required AWS credentials and enforcing user-defined access boundaries, such as bucket whitelisting.
Sources: packages/aws-s3-mcp/src/aws_s3_mcp/config.py:1-10, packages/aws-s3-mcp/README.md:46-52
Core Configuration Management
The system utilizes the S3Config class to parse and validate settings from environment variables. It follows a standardized naming convention and provides default values for non-critical settings like the AWS region and pagination limits.
Configuration Environment Variables
The server relies on the following environment variables for authentication and behavior control:
| Variable | Description | Default Value | Required |
|---|---|---|---|
AWS_ACCESS_KEY_ID | AWS access key for authentication. | None | Yes |
AWS_SECRET_ACCESS_KEY | AWS secret key for authentication. | None | Yes |
AWS_REGION | The AWS region to connect to. | us-east-1 | No |
S3_BUCKETS | Comma-separated list of allowed buckets. | All accessible | No |
S3_MAX_BUCKETS | Max number of buckets to list. | 5 | No |
S3_OBJECT_MAX_KEYS | Max objects per request. | 1000 | No |
Sources: packages/aws-s3-mcp/src/aws_s3_mcp/config.py:20-30, packages/aws-s3-mcp/README.md:105-115
Validation Logic
Upon initialization, the S3Config class performs internal validation to ensure operational stability. If credentials are missing, the system logs a warning but attempts to fall back to the default AWS credential chain. However, numeric constraints such as S3_MAX_BUCKETS and S3_OBJECT_MAX_KEYS must be greater than zero, or a ValueError is raised.
def _validate(self) -> None:
"""Validate configuration and raise errors for missing required values."""
if not self.aws_access_key_id or not self.aws_secret_access_key:
logger.warning(
"AWS credentials not found in environment variables. Will attempt to use default AWS credential chain."
)
if self.s3_max_buckets <= 0:
raise ValueError("S3_MAX_BUCKETS must be greater than 0")
if self.s3_object_max_keys <= 0:
raise ValueError("S3_OBJECT_MAX_KEYS must be greater than 0")
Sources: packages/aws-s3-mcp/src/aws_s3_mcp/config.py:43-55
Service Integration and Flow
The configuration settings are consumed by the S3Service to initialize the aioboto3 session and configure the S3 client with specific retry and timeout policies.
Initialization Flow
The following diagram illustrates how configuration is validated and used during service startup:
The S3Service explicitly validates credentials using session.get_credentials() during its __init__ phase to prevent runtime failures during tool execution.
Sources: packages/aws-s3-mcp/src/aws_s3_mcp/services/s3_service.py:38-60, tests/aws-s3-mcp/unit/services/test_s3_service.py:24-40
Operational Constraints in Services
Configuration values like s3_buckets and s3_object_max_keys are used as guards in service methods. For example, list_objects checks the requested bucket against the allowed list before initiating an AWS request.
Boto3 Client Configuration
The S3Service applies a hardcoded Config object to ensure reliable communication with AWS, utilizing the region specified in the global configuration instance.
| Setting | Value | Description |
|---|---|---|
retries | {"max_attempts": 3, "mode": "adaptive"} | Uses adaptive retry logic to handle throttling and transient errors. |
connect_timeout | 5 seconds | Time allowed to establish a connection. |
read_timeout | 60 seconds | Time allowed to receive a response from the server. |
max_pool_connections | 50 | Maximum number of concurrent connections in the pool. |
Sources: packages/aws-s3-mcp/src/aws_s3_mcp/services/s3_service.py:29-36
Summary
AWS S3 Configuration in this project is handled through a stateless, fail-safe pattern. By combining strict environment variable validation with the aioboto3 adaptive retry configuration, the system ensures that AI assistants can interact with S3 storage reliably while maintaining administrative control over which buckets are accessible.
Sources: packages/aws-s3-mcp/src/aws_s3_mcp/services/s3_service.py:23-27, packages/aws-s3-mcp/README.md:120-130