AWS Model Context Protocol (MCP) Server

Overview

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

Demo

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

Run Server Option 1: Using Docker (Recommended)

Note: The official image from GitHub Packages is multi-architecture and will automatically use the appropriate version for your system.Docker Image Tags:

Run Server Option 2: Using Python

Configuration

Security Considerations

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

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

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

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

• 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:

• 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., via curl). Strict IAM policies remain the most vital defense to limit the value of potentially exfiltrated credentials.

• 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 default stdio transport does not open network ports.

• AWS MCP Server provides the tool.

• You, the user, are responsible for:

Integrating with Claude Desktop

Configuration

1. Locate the Claude Desktop configuration file:

2. Edit the configuration file to include the AWS MCP Server:

3. Restart Claude Desktop to apply the changes

Example Interactions

Available Prompt Templates

Core Operations

Security & Compliance

Cost & Performance

Infrastructure & Architecture

Reliability & Monitoring

Security

Command Validation System

1. Basic Command Structure:

2. Security-Focused Command Filtering:

3. Pipe Command Security:

Default Security Configuration

1. Identity and Access Management (IAM) Risks

2. Audit and Logging Tampering

3. Sensitive Data Access and Protection

4. Network Security Risks

• All get-, list-, and describe- commands

• All help commands (--help, help)

• Simulation and testing commands (e.g., aws iam simulate-custom-policy)

Configuration Options

• Security Modes:

• Custom Configuration:

• Execution Controls:

Custom Security Rules Example

Security Examples

Security Best Practices

• Always use the default strict security mode in production

• Follow 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

Code Coverage

• Sets a target coverage threshold of 80%

• Excludes test files, setup files, and documentation from coverage reports

• Configures PR comments and status checks

Integration Testing

1. Set up AWS resources:

2. Run integration tests:

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

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

• Release versions: When a Git tag exists (e.g., 1.2.3), the version will be exactly that tag

• Development 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)

• Package version information

• Docker image labels

• Continuous integration builds

Creating Releases

License

AWS Model Context Protocol (MCP) Server

Overview

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

Demo

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

Run Server Option 1: Using Docker (Recommended)

Note: The official image from GitHub Packages is multi-architecture and will automatically use the appropriate version for your system.Docker Image Tags:

Run Server Option 2: Using Python

Configuration

Security Considerations

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

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

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

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

• 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:

• 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., via curl). Strict IAM policies remain the most vital defense to limit the value of potentially exfiltrated credentials.

• 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 default stdio transport does not open network ports.

• AWS MCP Server provides the tool.

• You, the user, are responsible for:

Integrating with Claude Desktop

Configuration

1. Locate the Claude Desktop configuration file:

2. Edit the configuration file to include the AWS MCP Server:

3. Restart Claude Desktop to apply the changes

Example Interactions

Available Prompt Templates

Core Operations

Security & Compliance

Cost & Performance

Infrastructure & Architecture

Reliability & Monitoring

Security

Command Validation System

1. Basic Command Structure:

2. Security-Focused Command Filtering:

3. Pipe Command Security:

Default Security Configuration

1. Identity and Access Management (IAM) Risks

2. Audit and Logging Tampering

3. Sensitive Data Access and Protection

4. Network Security Risks

• All get-, list-, and describe- commands

• All help commands (--help, help)

• Simulation and testing commands (e.g., aws iam simulate-custom-policy)

Configuration Options

• Security Modes:

• Custom Configuration:

• Execution Controls:

Custom Security Rules Example

Security Examples

Security Best Practices

• Always use the default strict security mode in production

• Follow 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

Code Coverage

• Sets a target coverage threshold of 80%

• Excludes test files, setup files, and documentation from coverage reports

• Configures PR comments and status checks

Integration Testing

1. Set up AWS resources:

2. Run integration tests:

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

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

• Release versions: When a Git tag exists (e.g., 1.2.3), the version will be exactly that tag

• Development 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)

• Package version information

• Docker image labels

• Continuous integration builds

Creating Releases

License