📌Overview

Purpose: The AWS Model Context Protocol (MCP) Server is designed to facilitate the execution of AWS CLI commands by AI assistants through the Model Context Protocol, enhancing their functionality and accessibility.

Overview: The AWS MCP Server acts as an intermediary between MCP-aware AI assistants (e.g., Claude Desktop, Cursor, Windsurf) and the AWS CLI. It allows these AI tools to efficiently access AWS resources and services by retrieving documentation and executing commands, which are then returned in a format that is easily understood by users.

Key Features:

Command Documentation: Provides detailed help on AWS CLI commands to assist users in understanding available options and usage effectively.
Command Execution: Enables the running of AWS CLI commands and returns the results in a human-readable format, streamlining the interaction with AWS services.
Unix Pipe Support: Allows filtering and transformation of AWS CLI output using standard Unix utilities, enhancing data processing capabilities.
Prompt Templates: Offers predefined templates for common AWS tasks that help users follow best practices without needing deep technical knowledge.
Docker Integration: Simplifies deployment with containerization, supporting multiple architectures (AMD64/x86_64 and ARM64) for broad compatibility.
AWS Authentication: Utilizes existing AWS credentials from the host machine, ensuring secure and seamless access to AWS services.

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 commands
Execute AWS CLI commands (aws_cli_pipeline) - Run commands with Unix pipes and receive formatted results optimized for AI consumption

flowchart LR
    AI[AI Assistant] <-->|MCP Protocol| Server[AWS MCP Server]
    Server <-->|Subprocess| AWS[AWS CLI]
    AWS <-->|API| Cloud[AWS Cloud]

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 (recommended) 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)

# Clone repository
git clone https://github.com/alexei-led/aws-mcp-server.git
cd aws-mcp-server

# Build and run Docker container
docker compose -f deploy/docker/docker-compose.yml up -d

The Docker image supports both AMD64/x86_64 (Intel/AMD) and ARM64 (Apple Silicon M1-M4, AWS Graviton) architectures.

You can pull the official image:

# 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.0

Run Server Option 2: Using Python

Use with Caution: Running natively requires careful environment setup and carries higher security risks compared to Docker deployment.

# Clone repository
git clone https://github.com/alexei-led/aws-mcp-server.git
cd aws-mcp-server

# Set up virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .

# Run the server
python -m aws_mcp_server

Configuration

Configure AWS MCP Server with environment variables:

Environment Variable	Description	Default
`AWS_MCP_TIMEOUT`	Command execution timeout in seconds	300
`AWS_MCP_MAX_OUTPUT`	Maximum output size in characters	100000
`AWS_MCP_TRANSPORT`	Transport protocol ("stdio" or "sse")	stdio
`AWS_PROFILE`	AWS profile to use	default
`AWS_REGION`	AWS region to use	us-east-1
`AWS_MCP_SECURITY_MODE`	Security mode ("strict" or "permissive")	strict
`AWS_MCP_SECURITY_CONFIG`	Path to custom security configuration file	""

Important: Securely manage AWS credentials provided to the server, whether via mounted ~/.aws files or environment variables. Ensure credentials follow least privilege principle (see Security Considerations). When using Docker, pass variables correctly to container environment.

Security Considerations

Security is paramount when executing commands against AWS. You are responsible for configuring and running the server securely.

1. Recommended Deployment: Docker Container

Isolation: Running inside Docker container is strongly recommended. It provides filesystem and process isolation. Potentially destructive Unix commands executed via pipes are contained and do not affect the host.
Controlled Environment: Docker ensures consistent environment and dependencies.

2. AWS Credentials and IAM Least Privilege

User Responsibility: You provide credentials.
Least Privilege: Credentials must have only minimal permissions needed. Never use root credentials.
Review Permissions Regularly: Audit IAM policies.
Impact Limitation: IAM policies limit scope of any command execution.

3. Trusted User Model

The server assumes the end user operating the MCP client is trusted and responsible for security.

4. Execution Risks

Commands run using shell=True for pipe support, which carries risks of command injection.
Mitigated operationally by trusted user model, Docker isolation, and strict IAM policies.
Credential exfiltration remains a risk if commands are manipulated; IAM restrictions reduce impact.

5. Network Exposure (SSE Transport)

If using sse transport, bind only to trusted interfaces or use firewalls/authentication proxies.
Default stdio transport uses no network ports.

6. Shared Responsibility Summary

You are responsible for:
- Running within Docker environment
- Providing least-privilege credentials
- Ensuring only trusted users have access
- Securing network environment as needed

Strict adherence to Docker deployment and IAM least privilege is essential for secure usage.

Integrating with Claude Desktop

Configuration

To manually integrate AWS MCP Server with Claude Desktop:

Locate Claude Desktop configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Edit the configuration 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. A hammer icon 🔨 will appear in the input box indicating AWS MCP Server is active.

flowchart TD
    subgraph "User Device"
        config[Edit claude_desktop_config.json]
        claude[Claude Desktop]
        docker[Docker Container]
        aws_creds[AWS Credentials]
    end
    
    subgraph "AWS Cloud"
        services[AWS Services]
    end
    
    subgraph "MCP Server Components"
        tools[AWS CLI Tools]
        resources[AWS Resources]
        templates[Prompt Templates]
    end
    
    config -->|Add MCP Server Config| claude
    claude -->|Docker Run Command| docker
    docker --- tools
    docker --- resources
    docker --- templates
    aws_creds -->|Mount Read-only| docker
    resources -.->|Read| aws_creds
    tools -->|API Calls| services

Example Interactions

Getting AWS CLI Documentation:

User: What are the available options for the AWS S3 cp command?

Claude: Let me get that information for you.

The AWS S3 cp command has the following options:

NAME
    cp - Copies a local file or S3 object to another location locally or in S3.

SYNOPSIS
    cp <LocalPath> <S3Uri> or <S3Uri> <LocalPath> or <S3Uri> <S3Uri> [--acl <value>] [--cache-control <value>] ...

Executing AWS CLI Commands:

User: List my S3 buckets

Claude: I'll list your S3 buckets for you.

2023-10-15 14:30:45 my-bucket-1
2023-11-20 09:15:32 my-bucket-2
2024-01-05 11:22:18 my-backup-bucket

Using Command Pipes:

User: List my S3 buckets that have "backup" in their name and show them in alphabetical order

Claude: Let me find that for you.

2024-01-05 11:22:18 my-backup-bucket
2024-03-01 09:44:12 weekly-backup-bucket
2024-03-15 13:10:57 database-backup-bucket

Accessing AWS Resources:

User: What AWS regions are available for me to use?

Claude: Let me check what AWS regions are available for you.

Available regions:
- us-east-1 (US East, N. Virginia) - Currently selected
- us-east-2 (US East, Ohio)
- us-west-1 (US West, N. California)
- us-west-2 (US West, Oregon)
- eu-west-1 (EU West, Ireland)
- eu-central-1 (EU Central, Frankfurt)
- ap-northeast-1 (Asia Pacific, Tokyo)
- ap-southeast-1 (Asia Pacific, Singapore)
- ap-southeast-2 (Asia Pacific, Sydney)

You're currently using the us-east-1 region.

Using Prompt Templates:

User: I need to perform a security audit of my S3 buckets

Claude: I'll help you audit the security of your S3 buckets.

Here are AWS CLI commands to perform a comprehensive security audit:

# List all buckets with public access settings
aws s3api list-buckets --query 'Buckets[*].Name' --output text | xargs -I {} aws s3api get-public-access-block --bucket {}

# Check bucket policies for public access
aws s3api list-buckets --query 'Buckets[*].Name' --output text | xargs -I {} aws s3api get-bucket-policy --bucket {} 2>/dev/null

# Identify buckets without encryption
aws s3api list-buckets --query 'Buckets[*].Name' --output text | xargs -I {} aws s3api get-bucket-encryption --bucket {} 2>/dev/null

# Check for buckets without logging enabled
aws s3api list-buckets --query 'Buckets[*].Name' --output text | xargs -I {} aws s3api get-bucket-logging --bucket {} 2>/dev/null

# Verify bucket versioning status
aws s3api list-buckets --query 'Buckets[*].Name' --output text | xargs -I {} aws s3api get-bucket-versioning --bucket {}

Available Prompt Templates

Core Operations

Prompt	Description	Parameters
create_resource	Generate commands to create AWS resources with best practices	resource_type, resource_name
resource_inventory	Create comprehensive inventory of resources	service, region (optional)
troubleshoot_service	Generate commands to troubleshoot service issues	service, resource_id
resource_cleanup	Identify and safely clean up resources	service, criteria (optional)

Security & Compliance

Prompt	Description	Parameters
security_audit	Audit security settings for a specific AWS service	service
security_posture_assessment	Comprehensive security assessment across your AWS environment	None
iam_policy_generator	Create least-privilege IAM policies	service, actions, resource_pattern (optional)
compliance_check	Check compliance with standards	compliance_standard, service (optional)

Cost & Performance

Prompt	Description	Parameters
cost_optimization	Find cost optimization opportunities for a service	service
performance_tuning	Optimize and tune performance of AWS resources	service, resource_id

Infrastructure & Architecture

Prompt	Description	Parameters
serverless_deployment	Deploy serverless applications with best practices	application_name, runtime (optional)
container_orchestration	Set up container environments (ECS/EKS)	cluster_name, service_type (optional)
vpc_network_design	Design and implement secure VPC networking	vpc_name, cidr_block (optional)
infrastructure_automation	Automate infrastructure management	resource_type, automation_scope (optional)
multi_account_governance	Implement secure multi-account strategies	account_type (optional)

Reliability & Monitoring

Prompt	Description	Parameters
service_monitoring	Set up comprehensive monitoring	service, metric_type (optional)
disaster_recovery	Implement enterprise-grade disaster recovery solutions	service, recovery_point_objective (optional)

Security

Command Validation System

Commands are validated through three layers:

Basic Command Structure
- Must start with 'aws' and contain a valid service
Security-Focused Command Filtering
- Blocks dangerous commands
- Allows safe, read-only patterns
- Uses regex matching for complex rules
Pipe Command Security
- Restricts Unix pipe commands to a safe allowlist
- Prevents filesystem manipulation and arbitrary execution

Default Security Configuration

IAM Risks (Blocked Commands Examples)

aws iam create-user
aws iam create-access-key
aws iam attach-*-policy
aws iam put-user-policy
aws iam create-policy
aws iam create-login-profile
aws iam deactivate-mfa-device
aws iam update-assume-role-policy

Audit and Logging Tampering

aws cloudtrail delete-trail
aws cloudtrail stop-logging
aws cloudtrail update-trail
aws config delete-configuration-recorder
aws guardduty delete-detector

Sensitive Data Protection

aws secretsmanager put-secret-value
aws secretsmanager delete-secret
aws kms schedule-key-deletion
aws kms disable-key
aws s3api put-bucket-policy
aws s3api delete-bucket-policy

Network Security Risks

aws ec2 authorize-security-group-ingress
aws ec2 authorize-security-group-egress
aws ec2 modify-instance-attribute

Allowed read-only operations include:

Commands starting with get-, list-, describe-
Help commands (--help, help)
Simulation and testing commands

Configuration Options

Security modes: strict (default), permissive (logs warnings but allows)
Custom YAML security configuration file (AWS_MCP_SECURITY_CONFIG)
Timeout and output limits via environment variables

Custom Security Rules Example

dangerous_commands:
  iam:
    - "aws iam create-user"
    - "aws iam attach-user-policy"
  lambda:
    - "aws lambda delete-function"
    - "aws lambda remove-permission"
  dynamodb:
    - "aws dynamodb delete-table"

safe_patterns:
  general:
    - "--help"
    - "--dry-run"
  iam:
    - "aws iam get-"
    - "aws iam list-"
  lambda:
    - "aws lambda list-functions"
    - "aws lambda get-function"

regex_rules:
  general:
    - pattern: "aws .* --profile\\s+root"
      description: "Prevent use of root profile"
      error_message: "Using the root profile is not allowed for security reasons"
  iam:
    - pattern: "aws iam create-user.*--user-name\\s+.*admin.*"
      description: "Prevent creation of admin users"
      error_message: "Creating users with 'admin' in the name is restricted"
    - pattern: "aws iam create-policy.*\"Effect\":\\s*\"Allow\".*\"Action\":\\s*\"\\*\".*\"Resource\":\\s*\"\\*\""
      description: "Prevent wildcards in policies"
      error_message: "Creating policies with '*' wildcards for both Action and Resource is not allowed"
  s3:
    - pattern: "aws s3api put-bucket-policy.*\"Effect\":\\s*\"Allow\".*\"Principal\":\\s*\"\\*\""
      description: "Prevent public bucket policies"
      error_message: "Creating bucket policies with public access is restricted"

Security Examples

Blocked commands:

aws iam create-user --user-name new-user
# Error: This command is restricted for security reasons.

aws iam attach-user-policy --user-name any-user --policy-arn arn:aws:iam::aws:policy/AdministratorAccess
# Error: Attaching Administrator policies is restricted.

aws ec2 authorize-security-group-ingress --group-id sg-12345 --protocol tcp --port 22 --cidr 0.0.0.0/0
# Error: Opening non-web ports to the entire internet (0.0.0.0/0) is restricted.

Allowed read-only operations:

aws iam list-users
aws s3 ls
aws ec2 describe-instances

Security Best Practices

Use strict mode in production
Deploy via Docker as recommended
Run with least-privilege AWS credentials
Customize security rules as needed

Development

Setting Up the Development Environment

pip install -e .
pip install -e ".[dev]"
make uv-install       # Install runtime dependencies
make uv-dev-install   # Install development dependencies

Makefile Commands

Common commands:

make test             # Run tests excluding integration
make test-unit        # Run only unit tests
make test-integration # Run only integration tests (needs AWS credentials)
make test-all         # Run all tests

make test-coverage    # Tests with coverage report (excluding integration)
make test-coverage-all # Tests with coverage report (including integration)

make lint             # Run linters
make lint-fix         # Lint and auto-fix issues
make format           # Format code

Run make help for the full list.

Code Coverage

Configured to track coverage via Codecov with threshold of 80%. Reports exclude test, setup, documentation files.

Integration Testing

Create an S3 bucket for tests and set environment variable:

export AWS_TEST_BUCKET=your-test-bucket-name

Run integration tests:

make test-all
make test-integration

# Or directly with pytest
pytest --run-integration
pytest --run-integration -m integration

Troubleshooting

Authentication: Verify AWS credentials configured properly
Connection: Ensure server is running and AI assistant configured correctly
Permissions: Check AWS credential permissions
Timeout: Increase AWS_MCP_TIMEOUT if needed

Why Deploy with Docker

Docker deployment is recommended for:

Security Benefits

Isolation: Container filesystem/process isolation protects host from accidental destructive commands
Read-only Credentials Mounts: Limits container changes
No Local AWS CLI Installation Needed
Clean Environment: Known, clean state every run

Reliability Advantages

Consistent configuration and dependencies
Avoid conflicts and maintain cross-platform consistency
Includes all necessary tools for command execution and piping

Other Benefits

Multi-architecture support (x86_64 and ARM64)
Easy updates by pulling new container images
Avoids Python environment conflicts
Version pinning for production stability

Versioning

Uses setuptools_scm for automatic version determination:

Release versions correspond to Git tags (e.g., 1.2.3)
Development versions include post-release and commit info (e.g., 1.2.3.post10+gb697684.d20250406)

Version info is included in package, Docker image labels, and CI builds.

Creating Releases

git tag -a 1.2.3 -m "Release version 1.2.3"
git push origin 1.2.3

CI/CD pipeline builds and publishes tagged Docker images automatically.

For details, see VERSION.md.

License

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