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.

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

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:

{
  "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