alexei-led/aws-mcp-server

CI PyPI Code Coverage Linter: Ruff Docker Image

Give Claude access to all 200+ AWS services through the AWS CLI.

Demo

Demo

What It Does

This MCP server lets Claude run AWS CLI commands on your behalf. Instead of wrapping each AWS API individually, it wraps the CLI itself—giving Claude complete AWS access through just two tools:

Tool	Purpose
aws_cli_help	Get documentation for any AWS command
aws_cli_pipeline	Execute AWS CLI commands with optional pipes (jq, grep, etc.)

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.