Claude learns commands on-demand using --help, then executes them. Your IAM policy controls what it can actually do.

flowchart LR
    Claude[Claude] -->|MCP| Server[AWS MCP Server]
    Server --> CLI[AWS CLI]
    CLI --> AWS[AWS Cloud]
    IAM[Your IAM Policy] -.->|controls| AWS

What's New

• Streamable HTTP transport — New streamable-http transport for web-based MCP clients, replacing the deprecated sse transport (#33)
• Input validation error handling — Validation errors now return proper MCP tool errors (isError: true) instead of regular results (#34)
• Server description — Server advertises its purpose to MCP clients via the instructions field (#35)
• Server icons — Server provides icon metadata for MCP client display (#36)
• Graceful shutdown — Server disconnects cleanly when the MCP client disconnects (#16)

Quick Start

Prerequisites

• AWS CLI installed
• AWS credentials configured (see AWS Credentials)
• uv installed (for uvx)

Claude Code

Add to your MCP settings (Cmd+Shift+P → "Claude: Open MCP Config"):

{
  "mcpServers": {
    "aws": {
      "command": "uvx",
      "args": ["aws-mcp"]
    }
  }
}

Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "aws": {
      "command": "uvx",
      "args": ["aws-mcp"]
    }
  }
}

Docker (More Secure)

Docker provides stronger isolation by running commands in a container:

{
  "mcpServers": {
    "aws": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "~/.aws:/home/appuser/.aws:ro",
        "ghcr.io/alexei-led/aws-mcp-server:latest"
      ]
    }
  }
}

Note: Replace ~/.aws with the full path on Windows (e.g., C:\Users\YOU\.aws).

Docker with Streamable HTTP Transport

For web-based MCP clients, use the streamable-http transport:

docker run --rm -p 8000:8000 \
  -e AWS_MCP_TRANSPORT=streamable-http \
  -v ~/.aws:/home/appuser/.aws:ro \
  ghcr.io/alexei-led/aws-mcp-server:latest

The server will be available at http://localhost:8000/mcp.

Note: The sse transport is deprecated. Use streamable-http instead.

AWS Credentials

The server uses the standard AWS credential chain. Your credentials are discovered automatically from:

1. Environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
2. Credentials file: ~/.aws/credentials
3. Config file: ~/.aws/config (for profiles and region)
4. IAM role: When running on EC2, ECS, or Lambda

To use a specific profile:

{
  "mcpServers": {
    "aws": {
      "command": "uvx",
      "args": ["aws-mcp"],
      "env": {
        "AWS_PROFILE": "my-profile"
      }
    }
  }
}

Configuration

AWS Settings

| Environment Variable | Description | Default | | ----------------------------- | ---------------------------------------------- | -------------------- | | AWS_PROFILE | AWS profile to use | default | | AWS_REGION | AWS region (also accepts AWS_DEFAULT_REGION) | us-east-1 | | AWS_CONFIG_FILE | Custom path to AWS config file | ~/.aws/config | | AWS_SHARED_CREDENTIALS_FILE | Custom path to credentials file | ~/.aws/credentials |

Server Settings

| 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, sse, or streamable-http) | stdio | | AWS_MCP_SANDBOX | Sandbox mode (auto, disabled, required) | auto | | AWS_MCP_SANDBOX_CREDENTIALS | Credential passing (env, aws_config, both) | both |

Security

Your IAM policy is your security boundary. This server executes whatever AWS commands Claude requests—IAM controls what actually succeeds.

Best practices:

• Use a least-privilege IAM role (only permissions Claude needs)
• Never use root credentials
• Consider Docker for additional host isolation

For detailed security architecture, see Security Documentation.

Documentation

• Usage Guide — Tools, resources, and prompt templates
• Security Architecture — IAM + Sandbox + Docker model
• Development Guide — Contributing and testing

License

MIT License — see LICENSE for details.