Integrates with Codecov to track code coverage metrics during CI/CD runs with target coverage thresholds and PR status checks
Provides containerized deployment option with multi-architecture support for AMD64/x86_64 and ARM64, with security isolation and consistent environment configuration
Distributes the containerized application through GitHub Packages with versioned releases and development builds tagged with Git commit SHA
Utilizes Mermaid diagrams to visualize architecture and workflows in documentation
Incorporates Pytest for unit testing and integration testing of AWS resource interactions
Supports local installation and execution using Python 3.13+ as an alternative to the Docker deployment method
Uses Ruff for code linting and formatting as part of the development workflow
AWS Model Context Protocol (MCP) Server
A lightweight service that enables AI assistants to execute AWS CLI commands through the Model Context Protocol (MCP).
Overview
The AWS MCP Server provides a bridge between MCP-aware AI assistants (like Claude Desktop, Cursor, Windsurf) and the AWS CLI. It enables these assistants to:
Retrieve AWS CLI documentation (
aws_cli_help
) - Get detailed help on AWS services and commandsExecute AWS CLI commands (
aws_cli_pipeline
) - Run commands with Unix pipes and receive formatted results optimized for AI consumption
Demo
The video demonstrates using Claude Desktop with AWS MCP Server to create a new AWS EC2 instance with AWS SSM agent installed.
Features
Command Documentation - Detailed help information for AWS CLI commands
Command Execution - Execute AWS CLI commands and return human-readable results
Unix Pipe Support - Filter and transform AWS CLI output using standard Unix pipes and utilities
AWS Resources Context - Access to AWS profiles, regions, account information, and environment details via MCP Resources
Prompt Templates - Pre-defined prompt templates for common AWS tasks following best practices
Docker Integration - Simple deployment through containerization with multi-architecture support (AMD64/x86_64 and ARM64)
AWS Authentication - Leverages existing AWS credentials on the host machine
Requirements
Docker (default) or Python 3.13+ (and AWS CLI installed locally)
AWS credentials configured
Getting Started
Note: For security and reliability, running the server inside a Docker container is the strongly recommended method. Please review the Security Considerations section for important considerations.
Run Server Option 1: Using Docker (Recommended)
The Docker image supports both AMD64/x86_64 (Intel/AMD) and ARM64 (Apple Silicon M1-M4, AWS Graviton) architectures.
Note: The official image from GitHub Packages is multi-architecture and will automatically use the appropriate version for your system.
# Use the latest stable version docker pull ghcr.io/alexei-led/aws-mcp-server:latest # Or pin to a specific version (recommended for production) docker pull ghcr.io/alexei-led/aws-mcp-server:1.0.0Docker Image Tags:
latest
: Latest stable release
x.y.z
(e.g.,1.0.0
): Specific version
sha-<commit-sha>
: Development builds, tagged with Git commit SHA (e.g.,sha-gb697684
)
Run Server Option 2: Using Python
Use with Caution: Running natively requires careful environment setup and carries higher security risks compared to the recommended Docker deployment. Ensure you understand the implications outlined in the Security Considerations section.
Configuration
The AWS MCP Server can be configured using environment variables:
Environment Variable | Description | Default |
| Command execution timeout in seconds | 300 |
| Maximum output size in characters | 100000 |
| Transport protocol to use ("stdio" or "sse") | stdio |
| AWS profile to use | default |
| AWS region to use | us-east-1 |
| Security mode ("strict" or "permissive") | strict |
| Path to custom security configuration file | "" |
Important: Securely manage the AWS credentials provided to the server, whether via mounted ~/.aws
files or environment variables. Ensure the credentials follow the principle of least privilege as detailed in the Security Considerations section. When running via Docker, ensure these variables are passed correctly to the container environment (e.g., using docker run -e VAR=value ...
).
Security Considerations
Security is paramount when executing commands against your AWS environment. While AWS MCP Server provides functionality, you are responsible for configuring and running it securely. Please adhere strictly to the following:
1. Recommended Deployment: Docker Container
Isolation: Running the server inside a Docker container is the strongly recommended and default deployment method. Containerization provides crucial filesystem and process isolation. Potentially destructive Unix commands (like
rm
,mv
) executed via pipes, even if misused, will be contained within the ephemeral Docker environment and will not affect your host machine's filesystem. The container can be easily stopped and recreated.Controlled Environment: Docker ensures a consistent environment with necessary dependencies, reducing unexpected behavior.
2. AWS Credentials and IAM Least Privilege (Critical)
User Responsibility: You provide the AWS credentials to the server (via mounted
~/.aws
or environment variables).Least Privilege is Essential: The server executes AWS CLI commands using the credentials you provide. It is absolutely critical that these credentials belong to an IAM principal (User or Role) configured with the minimum necessary permissions (least privilege) for only the AWS actions you intend to perform through this tool.
Do Not Use Root Credentials: Never use AWS account root user credentials.
Regularly Review Permissions: Periodically audit the IAM permissions associated with the credentials.
Impact Limitation: Properly configured IAM permissions are the primary mechanism for limiting the potential impact of any command executed via the server, whether intended or unintended. Even if a command were manipulated, it could only perform actions allowed by the specific IAM policy.
3. Trusted User Model
The server assumes the end-user interacting with the MCP client (e.g., Claude Desktop, Cursor) is the same trusted individual who configured the server and provided the least-privilege AWS credentials. Do not expose the server or connected client to untrusted users.
4. Understanding Execution Risks (Current Implementation)
Command Execution: The current implementation uses shell features (
shell=True
in subprocess calls) to execute AWS commands and handle Unix pipes. While convenient, this approach carries inherent risks if the input command string were manipulated (command injection).Mitigation via Operational Controls: In the context of the trusted user model and Docker deployment, these risks are mitigated operationally:
The trusted user is assumed not to provide intentionally malicious commands against their own environment.
Docker contains filesystem side-effects.
Crucially, IAM least privilege limits the scope of
Credential Exfiltration Risk: Despite containerization and IAM, a sophisticated command injection could potentially attempt to read the mounted credentials (
~/.aws
) or environment variables within the container and exfiltrate them (e.g., viacurl
). Strict IAM policies remain the most vital defense to limit the value of potentially exfiltrated credentials.
5. Network Exposure (SSE Transport)
If using the
sse
transport (which implies a network listener), ensure you bind the server only to trusted network interfaces (e.g.,localhost
) or implement appropriate network security controls (firewalls, authentication proxies) if exposing it more broadly. The defaultstdio
transport does not open network ports.
6. Shared Responsibility Summary
AWS MCP Server provides the tool.
You, the user, are responsible for:
Running it within the recommended secure Docker environment.
Providing and securely managing least-privilege AWS credentials.
Ensuring only trusted users interact with the server/client.
Securing the network environment if applicable.
By strictly adhering to Docker deployment and meticulous IAM least-privilege configuration, you establish the necessary operational controls for using the AWS MCP Server securely with its current implementation.
Integrating with Claude Desktop
Configuration
To manually integrate AWS MCP Server with Claude Desktop:
Locate the Claude Desktop configuration file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows:
%APPDATA%\Claude\claude_desktop_config.json
Edit the configuration file to include the AWS MCP Server:
{ "mcpServers": { "aws-mcp-server": { "command": "docker", "args": [ "run", "-i", "--rm", "-v", "/Users/YOUR_USER_NAME/.aws:/home/appuser/.aws:ro", "ghcr.io/alexei-led/aws-mcp-server:latest" ] } } }Restart Claude Desktop to apply the changes
After restarting, you should see a hammer 🔨 icon in the bottom right corner of the input box
This indicates that the AWS MCP Server is available for use
Example Interactions
Getting AWS CLI Documentation:
Executing AWS CLI Commands:
Using Command Pipes:
Accessing AWS Resources:
Using Prompt Templates:
Available Prompt Templates
The AWS MCP Server includes the following pre-defined prompt templates:
Core Operations
Prompt | Description | Parameters |
| Generate commands to create AWS resources with best practices |
,
|
| Create comprehensive inventory of resources |
,
(optional) |
| Generate commands to troubleshoot service issues |
,
|
| Identify and safely clean up resources |
,
(optional) |
Security & Compliance
Prompt | Description | Parameters |
| Audit security settings for a specific AWS service |
|
| Comprehensive security assessment across your AWS environment | None |
| Create least-privilege IAM policies |
,
,
(optional) |
| Check compliance with standards |
,
(optional) |
Cost & Performance
Prompt | Description | Parameters |
| Find cost optimization opportunities for a service |
|
| Optimize and tune performance of AWS resources |
,
|
Infrastructure & Architecture
Prompt | Description | Parameters |
| Deploy serverless applications with best practices |
,
(optional) |
| Set up container environments (ECS/EKS) |
,
(optional) |
| Design and implement secure VPC networking |
,
(optional) |
| Automate infrastructure management |
,
(optional) |
| Implement secure multi-account strategies |
(optional) |
Reliability & Monitoring
Prompt | Description | Parameters |
| Set up comprehensive monitoring |
,
(optional) |
| Implement enterprise-grade DR solutions |
,
(optional) |
Security
The AWS MCP Server implements a comprehensive multi-layered approach to command validation and security:
Command Validation System
The server validates all AWS CLI commands through a three-layer system:
Basic Command Structure:
Verifies commands start with 'aws' prefix and contain a valid service
Ensures proper command syntax
Security-Focused Command Filtering:
Dangerous Commands: Blocks commands that could compromise security
Safe Patterns: Explicitly allows read-only operations needed for normal use
Regex Pattern Matching: Prevents complex security risks with pattern matching
Pipe Command Security:
Validates Unix commands used in pipes
Restricts commands to a safe allowlist
Prevents filesystem manipulation and arbitrary command execution
Default Security Configuration
The default security configuration focuses on preventing the following attack vectors:
1. Identity and Access Management (IAM) Risks
Blocked Command | Security Risk |
| Creates potential backdoor accounts with persistent access |
| Creates long-term credentials that can be stolen or misused |
| Potential privilege escalation via policy attachments |
| Inline policies can grant excessive permissions |
| Creating new policies with potentially dangerous permissions |
| Creates console passwords for existing users |
| Disables multi-factor authentication, weakening security |
| Modifies trust relationships, enabling privilege escalation |
2. Audit and Logging Tampering
Blocked Command | Security Risk |
| Removes audit trail of AWS activity |
| Stops collecting activity logs, creating blind spots |
| Can redirect or modify logging configuration |
| Disables AWS Config recording of resource changes |
| Disables threat detection capabilities |
3. Sensitive Data Access and Protection
Blocked Command | Security Risk |
| Modifies sensitive credentials |
| Removes sensitive credentials |
| Schedules deletion of encryption keys, risking data loss |
| Disables encryption keys, potentially exposing data |
| Can create public S3 buckets, exposing data |
| Removes protective policies from buckets |
4. Network Security Risks
Blocked Command | Security Risk |
| Opens inbound network access, potential exposure |
| Opens outbound network access, potential data exfiltration |
| Can alter security properties of instances |
Many read-only operations that match these patterns are explicitly allowed via safe patterns:
All
get-
,list-
, anddescribe-
commandsAll help commands (
--help
,help
)Simulation and testing commands (e.g.,
aws iam simulate-custom-policy
)
Configuration Options
Security Modes:
strict
(default): Enforces all security validationspermissive
: Logs warnings but allows execution (use with caution)
Custom Configuration:
Override default security rules via YAML configuration file
Configure service-specific dangerous commands
Define custom safe patterns and regex rules
Environment variable:
AWS_MCP_SECURITY_CONFIG
Execution Controls:
Timeouts prevent long-running commands (default: 300 seconds)
Output size limits prevent memory issues
Environment variables:
AWS_MCP_TIMEOUT
,AWS_MCP_MAX_OUTPUT
Custom Security Rules Example
You can create custom security rules by defining a YAML configuration file:
Security Examples
The system follows IAM best practices, focusing on preventing escalation of privilege:
Security Best Practices
Always use the default
strict
security mode in productionFollow the deployment recommendations in Security Considerations
Run with least-privilege AWS credentials
For custom configurations, focus on your security requirements
Development
Setting Up the Development Environment
Makefile Commands
The project includes a Makefile with various targets for common tasks:
For a complete list of available commands, run make help
.
Code Coverage
The project includes configuration for Codecov to track code coverage metrics. The configuration is in the codecov.yml
file, which:
Sets a target coverage threshold of 80%
Excludes test files, setup files, and documentation from coverage reports
Configures PR comments and status checks
Coverage reports are automatically generated during CI/CD runs and uploaded to Codecov.
Integration Testing
Integration tests verify AWS MCP Server works correctly with actual AWS resources. To run them:
Set up AWS resources:
Create an S3 bucket for testing
Set the environment variable:
export AWS_TEST_BUCKET=your-test-bucket-name
Ensure your AWS credentials are configured
Run integration tests:
# Run all tests including integration tests make test-all # Run only integration tests make test-integration
Or you can run the pytest commands directly:
Troubleshooting
Authentication Issues: Ensure your AWS credentials are properly configured
Connection Errors: Verify the server is running and AI assistant connection settings are correct
Permission Errors: Check that your AWS credentials have the necessary permissions
Timeout Errors: For long-running commands, increase the
AWS_MCP_TIMEOUT
environment variable
Why Deploy with Docker
Deploying AWS MCP Server via Docker is the recommended approach, offering significant security and reliability advantages that form the core of the tool's secure usage pattern:
Security Benefits
Isolation (Primary Mitigation): The Docker container provides essential filesystem and process isolation. AWS CLI commands and piped Unix utilities run in a contained environment. Accidental or misused commands affecting the filesystem are limited to the container, protecting your host machine.
Controlled Credential Access: When mounting credentials, using the
:ro
(read-only) flag limits the container's ability to modify your AWS configuration files.No Local Installation: Avoids installing the AWS CLI and its dependencies directly on your host system.
Clean Environment: Each container run starts with a known, clean state.
Reliability Advantages
Consistent Configuration: All required tools (AWS CLI, SSM plugin, jq) are pre-installed and properly configured
Dependency Management: Avoid version conflicts between tools and dependencies
Cross-Platform Consistency: Works the same way across different operating systems
Complete Environment: Includes all necessary tools for command pipes, filtering, and formatting
Other Benefits
Multi-Architecture Support: Runs on both Intel/AMD (x86_64) and ARM (Apple Silicon, AWS Graviton) processors
Simple Updates: Update to new versions with a single pull command
No Python Environment Conflicts: Avoids potential conflicts with other Python applications on your system
Version Pinning: Easily pin to specific versions for stability in production environments
Versioning
This project uses setuptools_scm to automatically determine versions based on Git tags:
Release versions: When a Git tag exists (e.g.,
1.2.3
), the version will be exactly that tagDevelopment versions: For commits without tags, a development version is generated in the format:
<last-tag>.post<commits-since-tag>+g<commit-hash>.d<date>
(e.g.,1.2.3.post10+gb697684.d20250406
)
The version is automatically included in:
Package version information
Docker image labels
Continuous integration builds
Creating Releases
To create a new release version:
The CI/CD pipeline will automatically build and publish Docker images with appropriate version tags.
For more detailed information about the version management system, see VERSION.md.
License
This project is licensed under the MIT License - see the LICENSE file for details.
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
A lightweight service that enables AI assistants to execute AWS CLI commands through the Model Context Protocol (MCP), allowing AI tools to retrieve AWS documentation and interact with AWS services.
Related MCP Servers
- AsecurityFlicenseAqualityA Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with your AWS environment. This allows for natural language querying and management of your AWS resources during conversations. Think of better Amazon Q alternative.Last updated -3285
- AsecurityAlicenseAqualityEnables AI models to interact with AWS Lambda functions via the MCP protocol, allowing access to private resources, real-time data, and custom computation in a secure environment.Last updated -2108MIT License
- AsecurityAlicenseAqualityA server that enables AI assistants to execute terminal commands and retrieve outputs via the Model Context Protocol (MCP).Last updated -317MIT License
- -securityFlicense-qualityAn MCP server that enables Claude to generate and execute AWS CLI commands, allowing users to manage AWS resources through natural language conversations.Last updated -2