# mcp-aws-cost-doctor

MCP-native AWS cost diagnostic server. Exposes a small set of read-only
tools that an AI agent (Claude, etc) can call to surface common cost
leaks in an AWS account: idle EC2, orphaned EBS volumes, unused
Elastic IPs, oversized RDS, NAT gateways in dev VPCs.

Read-only by construction. No `delete_*`, no `modify_*`, no
`terminate_*`. The server can scan an account, never change it.

```mermaid
flowchart LR
    A[Claude / MCP client] -- tool call --> S[mcp-aws-cost-doctor]
    S -- boto3 describe_* --> AWS[AWS account<br/>IAM ReadOnlyAccess]
    AWS --> S
    S -- ranked findings + est. monthly waste --> A
```

## Tools exposed (implemented)

| Tool | Returns |
|---|---|
| `list_orphaned_ebs(region)` | Unattached EBS volumes (billed, never mounted) |
| `list_old_snapshots(region, min_age_days=90)` | EBS snapshots whose source volume was deleted |
| `list_unused_eips(region)` | Elastic IPs allocated but not associated |
| `summarize_findings(region)` | Run all implemented scanners + return ranked summary |

## Roadmap

Additional scanners planned (PRs welcome):

- `list_idle_ec2(region)` — EC2 with avg CPU < 5% over last 14 days (needs CloudWatch)
- `list_oversized_rds(region)` — RDS with avg CPU < 20% + low connections
- `list_s3_no_lifecycle()` — S3 buckets with no lifecycle policy on standard storage
- `list_nat_in_dev_vpcs(region)` — NAT gateways in VPCs tagged `Env=dev|staging`

## Why MCP

`aws-cost-optimizer-cli` (sibling repo) does the same scan as a
standalone CLI. This server wraps the same scanners as MCP tools so
they can be called by an AI agent inside a conversation:

```
> Can you scan us-east-1 for cost leaks?

[claude calls list_orphaned_ebs(region="us-east-1") + list_unused_eips(region="us-east-1") + ...]

I found 12 cost leaks totaling ~$340/mo:
- 3 unattached EBS volumes (~$180/mo)
- 4 unused Elastic IPs (~$15/mo)
- 1 oversized RDS db.r6g.xlarge with avg CPU 8% (~$140/mo)
...
```

## Quick start

```bash
pip install -e .

# Set AWS credentials however you normally do (profile, env, instance role)
export AWS_PROFILE=mycompany-readonly

# Run the MCP server (stdio transport — wire into Claude Desktop config)
python -m mcp_aws_cost_doctor.server
```

For Claude Desktop, add to your MCP config:

```json
{
  "mcpServers": {
    "aws-cost-doctor": {
      "command": "python",
      "args": ["-m", "mcp_aws_cost_doctor.server"],
      "env": {"AWS_PROFILE": "mycompany-readonly"}
    }
  }
}
```

## Safety

- **IAM**: server is meant to run with `ReadOnlyAccess` (or a tighter
  custom policy — see `iam/policy.json`). It does not attempt to write.
- **Rate limits**: each tool batches `describe_*` calls and respects
  AWS API throttling.
- **No mutation**: tools are named `list_*` / `summarize_*`. There is
  no `delete_*` / `terminate_*`. By design.

## Status

Early — basic tools land first, more arrive as the underlying
`aws-cost-optimizer-cli` matures. PRs welcome.

## License

MIT