AWS MCP Server

1# AWS MCP Server
2 
3[![CI](https://github.com/alexei-led/aws-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/alexei-led/aws-mcp-server/actions/workflows/ci.yml)
4[![PyPI](https://img.shields.io/pypi/v/aws-mcp)](https://pypi.org/project/aws-mcp/)
5[![Code Coverage](https://codecov.io/gh/alexei-led/aws-mcp-server/branch/main/graph/badge.svg?token=K8vdP3zyuy)](https://codecov.io/gh/alexei-led/aws-mcp-server)
6[![Linter: Ruff](https://img.shields.io/badge/Linter-Ruff-brightgreen?style=flat-square)](https://github.com/alexei-led/aws-mcp-server)
7[![Docker Image](https://img.shields.io/badge/ghcr.io-aws--mcp--server-blue?logo=docker)](https://github.com/alexei-led/aws-mcp-server/pkgs/container/aws-mcp-server)
8 
9Give Claude access to all 200+ AWS services through the AWS CLI.
10 
11## Demo
12 
13[Demo](https://private-user-images.githubusercontent.com/1898375/424996801-b51ddc8e-5df5-40c4-8509-84c1a7800d62.mp4?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NDI0NzY5OTUsIm5iZiI6MTc0MjQ3NjY5NSwicGF0aCI6Ii8xODk4Mzc1LzQyNDk5NjgwMS1iNTFkZGM4ZS01ZGY1LTQwYzQtODUwOS04NGMxYTc4MDBkNjIubXA0P1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI1MDMyMCUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNTAzMjBUMTMxODE1WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9NjgwNTM4MDVjN2U4YjQzN2Y2N2Y5MGVkMThiZTgxYWEyNzBhZTlhMTRjZDY3ZDJmMzJkNmViM2U4M2U4MTEzNSZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QifQ.tIb7uSkDpSaspIluzCliHS8ATmlzkvEnF3CiClD-UGQ)
14 
15## What It Does
16 
17This 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:
18 
19| Tool               | Purpose                                                           |
20| ------------------ | ----------------------------------------------------------------- |
21| `aws_cli_help`     | Get documentation for any AWS command                             |
22| `aws_cli_pipeline` | Execute AWS CLI commands with optional pipes (`jq`, `grep`, etc.) |
23 
24Claude learns commands on-demand using `--help`, then executes them. Your IAM policy controls what it can actually do.
25 
26```mermaid
27flowchart LR
28    Claude[Claude] -->|MCP| Server[AWS MCP Server]
29    Server --> CLI[AWS CLI]
30    CLI --> AWS[AWS Cloud]
31    IAM[Your IAM Policy] -.->|controls| AWS
32```
33 
34## What's New
35 
36- **Streamable HTTP transport** — New `streamable-http` transport for web-based MCP clients, replacing the deprecated `sse` transport ([#33](https://github.com/alexei-led/aws-mcp-server/issues/33))
37- **Input validation error handling** — Validation errors now return proper MCP tool errors (`isError: true`) instead of regular results ([#34](https://github.com/alexei-led/aws-mcp-server/issues/34))
38- **Server description** — Server advertises its purpose to MCP clients via the `instructions` field ([#35](https://github.com/alexei-led/aws-mcp-server/issues/35))
39- **Server icons** — Server provides icon metadata for MCP client display ([#36](https://github.com/alexei-led/aws-mcp-server/issues/36))
40- **Graceful shutdown** — Server disconnects cleanly when the MCP client disconnects ([#16](https://github.com/alexei-led/aws-mcp-server/issues/16))
41 
42## Quick Start
43 
44### Prerequisites
45 
46- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) installed
47- AWS credentials configured (see [AWS Credentials](#aws-credentials))
48- [uv](https://docs.astral.sh/uv/getting-started/installation/) installed (for `uvx`)
49 
50### Claude Code
51 
52Add to your MCP settings (Cmd+Shift+P → "Claude: Open MCP Config"):
53 
54```json
55{
56  "mcpServers": {
57    "aws": {
58      "command": "uvx",
59      "args": ["aws-mcp"]
60    }
61  }
62}
63```
64 
65### Claude Desktop
66 
67Add to your Claude Desktop config file:
68 
69**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
70**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
71 
72```json
73{
74  "mcpServers": {
75    "aws": {
76      "command": "uvx",
77      "args": ["aws-mcp"]
78    }
79  }
80}
81```
82 
83### Docker (More Secure)
84 
85Docker provides stronger isolation by running commands in a container:
86 
87```json
88{
89  "mcpServers": {
90    "aws": {
91      "command": "docker",
92      "args": [
93        "run",
94        "-i",
95        "--rm",
96        "-v",
97        "~/.aws:/home/appuser/.aws:ro",
98        "ghcr.io/alexei-led/aws-mcp-server:latest"
99      ]
100    }
101  }
102}
103```
104 
105> **Note**: Replace `~/.aws` with the full path on Windows (e.g., `C:\Users\YOU\.aws`).
106 
107### Docker with Streamable HTTP Transport
108 
109For web-based MCP clients, use the `streamable-http` transport:
110 
111```bash
112docker run --rm -p 8000:8000 \
113  -e AWS_MCP_TRANSPORT=streamable-http \
114  -v ~/.aws:/home/appuser/.aws:ro \
115  ghcr.io/alexei-led/aws-mcp-server:latest
116```
117 
118The server will be available at `http://localhost:8000/mcp`.
119 
120> **Note**: The `sse` transport is deprecated. Use `streamable-http` instead.
121 
122## AWS Credentials
123 
124The server uses the standard AWS credential chain. Your credentials are discovered automatically from:
125 
1261. **Environment variables**: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`
1272. **Credentials file**: `~/.aws/credentials`
1283. **Config file**: `~/.aws/config` (for profiles and region)
1294. **IAM role**: When running on EC2, ECS, or Lambda
130 
131To use a specific profile:
132 
133```json
134{
135  "mcpServers": {
136    "aws": {
137      "command": "uvx",
138      "args": ["aws-mcp"],
139      "env": {
140        "AWS_PROFILE": "my-profile"
141      }
142    }
143  }
144}
145```
146 
147## Configuration
148 
149### AWS Settings
150 
151| Environment Variable          | Description                                    | Default              |
152| ----------------------------- | ---------------------------------------------- | -------------------- |
153| `AWS_PROFILE`                 | AWS profile to use                             | `default`            |
154| `AWS_REGION`                  | AWS region (also accepts `AWS_DEFAULT_REGION`) | `us-east-1`          |
155| `AWS_CONFIG_FILE`             | Custom path to AWS config file                 | `~/.aws/config`      |
156| `AWS_SHARED_CREDENTIALS_FILE` | Custom path to credentials file                | `~/.aws/credentials` |
157 
158### Server Settings
159 
160| Environment Variable          | Description                                      | Default  |
161| ----------------------------- | ------------------------------------------------ | -------- |
162| `AWS_MCP_TIMEOUT`             | Command execution timeout in seconds             | `300`    |
163| `AWS_MCP_MAX_OUTPUT`          | Maximum output size in characters                | `100000` |
164| `AWS_MCP_TRANSPORT`           | Transport protocol (`stdio`, `sse`, or `streamable-http`) | `stdio`  |
165| `AWS_MCP_SANDBOX`             | Sandbox mode (`auto`, `disabled`, `required`)    | `auto`   |
166| `AWS_MCP_SANDBOX_CREDENTIALS` | Credential passing (`env`, `aws_config`, `both`) | `both`   |
167 
168## Security
169 
170**Your IAM policy is your security boundary.** This server executes whatever AWS commands Claude requests—IAM controls what actually succeeds.
171 
172Best practices:
173 
174- Use a **least-privilege IAM role** (only permissions Claude needs)
175- **Never use root credentials**
176- Consider **Docker** for additional host isolation
177 
178For detailed security architecture, see [Security Documentation](docs/SECURITY.md).
179 
180## Documentation
181 
182- [Usage Guide](docs/USAGE.md) — Tools, resources, and prompt templates
183- [Security Architecture](docs/SECURITY.md) — IAM + Sandbox + Docker model
184- [Development Guide](docs/DEVELOPMENT.md) — Contributing and testing
185 
186## License
187 
188MIT License — see [LICENSE](LICENSE) for details.
189