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:

1. Retrieve AWS CLI documentation (aws_cli_help) - Get detailed help on AWS services and commands
2. 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]

Demo

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)

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

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

Docker 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.

# 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

The AWS MCP Server can be configured using environment variables:

| Environment Variable | Description | Default | |--------------------------|REDACTED|-----------| | AWS_MCP_TIMEOUT | Command execution timeout in seconds | 300 | | AWS_MCP_MAX_OUTPUT | Maximum output size in characters | 100000 | | AWS_MCP_TRANSPORT | Transport protocol to use ("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 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…