aws-fleet
2menai/aws-fleet
Generic multi-agent AWS diagnostic & remediation fleet for Claude Code — read-only scanning, Well-Architected assessment, and HTML intelligence reports.
Instalação
npx convez-ai 2menai/aws-fleet1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
AWS Diagnostic & Remediation Fleet
A multi-agent project that scans AWS accounts, maps what's running, assesses it against the Well-Architected Framework, and produces a prioritized HTML intelligence report — using Claude Code + the AWS MCP Server (generally available since May 6, 2026, and part of the Agent Toolkit for AWS). With explicit approval, it also remediates findings.
What This Is
Open this folder in Claude Code and it becomes a fleet of AWS specialist agents that can:
- Scan accounts (read-only) — Inventory and map live resources across one or more accounts
- Assess — Score the environment against Well-Architected pillars; rank findings by severity × effort
- Report — Render a styled HTML intelligence report (see
report.template.html) - Remediate (opt-in) — Apply approved fixes; production changes confirmed per action
- Use AWS Agent Skills — Curated, on-demand best-practice guidance from AWS service teams
The AWS MCP Server is a managed remote server — AWS hosts and maintains it, with IAM-based guardrails, CloudTrail logging, and CloudWatch metrics built in. You connect to it through a small local auth bridge (see Connection below).
Read-only by design. The default .mcp.json runs the MCP proxy with
--read-only, so a normal session cannot mutate anything. Remediation is a deliberate opt-in (see Enabling remediation). This repo ships no real account data — every run discovers your environment live.
The Fleet
om orchestrates seven specialist lenses. Each scans read-only, assesses against the Well-Architected Framework, and surfaces prioritized findings (finding → pillar → severity → effort → recommendation). Remediation is opt-in and applied one approved change at a time; production is confirmed per action.
| Agent | Lens — what it inspects | Well-Architected focus | Mutates? |
|---|---|---|---|
om | Orchestrator — discovers the environment, dispatches specialists in parallel, synthesizes the single HTML intelligence report | All pillars | Only via approved remediation |
network-architect | VPCs, subnets, route tables, NACLs, security groups, Internet/NAT/Transit gateways, peering, VPC endpoints, Flow Logs | Security · Reliability | Opt-in, 1 change at a time |
compute-engineer | EC2, ECS/Fargate, EKS, Lambda, Auto Scaling, AMIs, instance profiles — right-sizing, IMDSv2, Graviton/Spot, healthchecks, runtime currency | Performance · Cost · Reliability | Opt-in, 1 change at a time |
security-hardener | IAM roles/policies/trust, OIDC scoping, security groups, KMS, public exposure (S3/ALB), GuardDuty, Secrets Manager, encryption, CloudTrail | Security | Opt-in, 1 change at a time |
data-engineer | RDS/Aurora, DynamoDB, S3, ElastiCache, queues — encryption, backups/PITR, versioning, public access, multi-AZ | Reliability · Security · Cost | Opt-in, 1 change at a time |
devops-specialist | IaC footprint, CI/CD pipelines & OIDC roles, observability (CloudWatch alarms/dashboards/log retention), CloudTrail, tagging hygiene, drift | Operational Excellence | Opt-in, 1 change at a time |
cost-optimizer | Cost/usage, right-sizing, Savings Plans/RIs, Spot/Graviton, idle & orphaned-resource waste (adds estimated monthly savings) | Cost Optimization | Opt-in, 1 change at a time |
pre-mortem | Failure modes, blast radius, capacity/service limits, single points of failure — reasons backward from "what could go wrong" | Reliability · Security | Never — read-only |
Quick Start
Prerequisites
# 1. Install AWS CLI v2.32.0+
brew install awscli
# 2. Install uv (runs the local mcp-proxy-for-aws auth bridge)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 3. Authenticate however your org does — the server uses your standard AWS credential chain:
aws login # simplified flow (auto-rotates creds)
# or
aws sso login --profile <your-profile> # IAM Identity Center / SSO
# or set AWS_PROFILE / standard env vars / a [default] profile
# 4. Verify (add --profile <name> if you don't use a default profile)
aws sts get-caller-identity
Profile-agnostic by design: this repo's .mcp.json hardcodes no AWS profile. The proxy resolves credentials from the standard AWS chain (
AWS_PROFILE, env vars, SSO, or a[default]profile), so each user supplies their own. If you only have named profiles (no[default]), setAWS_PROFILEbefore launching, e.g.export AWS_PROFILE=<your-profile>.
Note:
uvxdoes not run the MCP server — AWS hosts that remotely. It runsmcp-proxy-for-aws, a thin local bridge that SigV4-signs each request with your AWS credentials and forwards it to the managed endpoint. See Connection.
Launch
# Open this folder in Claude Code
cd /path/to/aws-fleet
claude
Claude Code will automatically:
- Load
CLAUDE.md(fleet instructions) - Connect to the AWS MCP Server (read-only scanner) via
.mcp.json - Be ready to scan and report
Example Commands
> scan this account
> report # generate the full HTML intelligence report
> security audit
> cost check
> pre-mortem
> diagram # ASCII architecture from live state
> status
> remediate <finding> # requires the write server (see Enabling remediation)
Connection
The AWS MCP Server is a single managed remote endpoint. Your MCP client reaches it through the local mcp-proxy-for-aws bridge (launched via uvx), which handles SigV4 authentication. This repo's .mcp.json is already wired for us-east-1:
{
"mcpServers": {
"aws-mcp": {
"command": "uvx",
"timeout": 100000,
"transport": "stdio",
"args": [
"mcp-proxy-for-aws==1.6.0",
"https://aws-mcp.us-east-1.api.aws/mcp",
"--metadata", "AWS_REGION=us-east-1",
"--read-only"
]
}
}
}
The endpoint Region selects which managed server you connect to; the AWS_REGION metadata sets the default Region for the operations it performs (these can differ, and you can always override per prompt, e.g. "…in us-west-2").
| Region | Endpoint |
|---|---|
US East (N. Virginia) — us-east-1 (default here) | https://aws-mcp.us-east-1.api.aws/mcp |
Europe (Frankfurt) — eu-central-1 | https://aws-mcp.eu-central-1.api.aws/mcp |
No offline mode for the managed server — the proxy must reach the AWS endpoint. For fully air-gapped use, the separate open-source
awslabs/mcpservers exist, but AWS recommends migrating to the managed server.
Multi-account (cross-account / cross-role)
Configure named profiles in ~/.aws/config, then the agent can target a profile per command — no session switching:
# ~/.aws/config
[profile lab]
sso_session = my-sso
sso_account_id = 111111111111
sso_role_name = LabAdmin
[profile prod-readonly]
sso_session = my-sso
sso_account_id = 222222222222
sso_role_name = ReadOnly
> using the prod-readonly profile, scan this account
> using the staging profile, report
Enabling remediation
Scanning is read-only. To let the fleet apply approved fixes, add a second, write-capable MCP server (the same proxy without --read-only) and use it only during an intentional remediation session:
{
"mcpServers": {
"aws-remediate": {
"command": "uvx",
"timeout": 100000,
"transport": "stdio",
"args": [
"mcp-proxy-for-aws==1.6.0",
"https://aws-mcp.us-east-1.api.aws/mcp",
"--metadata", "AWS_REGION=us-east-1"
]
}
}
}
Even with the write server enabled, the fleet proposes each change and waits for your explicit approval before applying it; production changes are confirmed per action. For an even stronger guarantee, back this with an IAM role that only permits the specific mutations you intend (see IAM Guardrails & Observability).
GA Capabilities
| Capability | What it gives you |
|---|---|
call_aws | Invoke any of 15,000+ AWS API operations (incl. file uploads, long-running ops) via one tool |
run_script | Run Python server-side in a sandbox — inherits your IAM permissions, no network or local filesystem access |
| Agent Skills | Curated AWS best-practice guidance loaded on demand (retrieve_skill), low context-window cost |
| Doc discovery | search_documentation / read_documentation retrieve current AWS docs — no credentials required |
| IAM guardrails | Org-controlled access via IAM context keys (separate human vs. agent perms, read-only restrictions) |
| Observability | CloudWatch metrics under the AWS-MCP namespace + full CloudTrail records, built in |
In the MCP client these tools surface with an
aws___prefix (e.g.aws___call_aws,aws___run_script,aws___retrieve_skill). File uploads and long-running operations are handled by companion tools (aws___get_presigned_url,aws___get_tasks). When the server runs with--read-only, the mutating tools (call_aws,run_script) are withheld.
Project Structure
aws-fleet/
├── CLAUDE.md # Fleet instructions — roles, read-only directive, guardrails
├── .mcp.json # AWS MCP Server connection (read-only scanner)
├── .claude/agents/ # 8 specialist lenses (network, compute, security, data, devops, cost, pre-mortem, om)
├── report.template.html # HTML report schema (placeholder data only)
├── CHANGELOG.md # Change history
├── README.md # This file
└── reports/ # Generated reports (gitignored — contain live data)
Configuration
Change Default Region
Edit .mcp.json — change AWS_REGION=us-east-1 to your preferred region (and the endpoint, to scan from eu-central-1).
Set your profiles / accounts
This repo is profile-agnostic — nothing is hardcoded. Supply credentials via the standard AWS chain (AWS_PROFILE, SSO, or a [default] profile). Optionally fill in the profiles: / accounts: placeholders in CLAUDE.md for your own reference.
IAM Guardrails & Observability
Because the server runs on your IAM credentials, what the agent can do is governed by IAM — not by trusting the prompt. Scope an agent with a dedicated role and IAM context keys to, for example, allow read-only discovery while blocking mutations, or separate human vs. agent permissions. See Understanding IAM for managed AWS MCP servers.
Every call is auditable out of the box: CloudTrail records the API activity and CloudWatch publishes metrics under the AWS-MCP namespace (tracked separately from direct API calls).
Defaults
| Setting | Value |
|---|---|
| Region | us-east-1 |
| Mode | read-only scan (remediation is opt-in) |
| Profiles | none hardcoded — profile-agnostic |
| Deliverable | HTML intelligence report (report.template.html schema) |
| Remediation IaC | Terraform default, CDK TypeScript accepted |
| MCP proxy | mcp-proxy-for-aws==1.6.0 (version-pinned) |
| Observability | CloudTrail + CloudWatch (AWS-MCP namespace), on by default |
Troubleshooting
| Problem | Fix |
|---|---|
NoCredentials / server won't connect | Authenticate (aws login or aws sso login --profile <name>). If you have no [default] profile, export AWS_PROFILE=<name> before launching Claude Code. |
ExpiredTokenException | Re-authenticate as above, then restart your MCP client to re-initialize. |
| Tools not loading | Confirm uvx is installed (which uvx) and creds resolve (aws sts get-caller-identity); restart Claude Code so .mcp.json reloads. |
| Wrong region | Override per prompt ("...in us-west-2"), or change AWS_REGION in .mcp.json. |
Cost Notes
Scanning is read-only and effectively free — describe/list/get calls and documentation lookups incur no resource charges, and there's no charge for the MCP server itself (you pay only for any resources remediation creates). Generated reports are local files (gitignored), not AWS resources.
Data Handling
This repo contains no real account data. Generated reports (report.html, reports/) and local Claude config (.claude/settings.local.json) are gitignored because they reflect your live environment — never commit them. report.template.html is placeholder-only and safe to share.