aws-mcp-audit (MVP)

A contractor-friendly read-only AWS assessment tool (MCP server) that inventories an AWS environment, runs deterministic security/ops checks, and generates actionable reports plus a cost/usage snapshot.

Quick start (uv)

uv sync
uv run python -m aws_mcp_audit.server

Claude Desktop (Windows) example config

Put this in %APPDATA%\Claude\claude_desktop_config.json and adjust the directory path:

{
  "mcpServers": {
    "aws-mcp-audit": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\D_Drive\\Dev\\aws-mcp-audit",
        "run",
        "python",
        "-m",
        "aws_mcp_audit.server"
      ]
    }
  }
}

Tool usage (conceptual)

aws_whoami(auth?)
collect_snapshot(scope, auth?) -> snapshot_id
run_checks(snapshot_id) -> finding_set_id
cost_signals(snapshot_id)
cost_explorer_summary(days=30, auth?) (optional permissions)
generate_report(snapshot_id, finding_set_id, format="md|pdf")

Auth

All tools accept an optional auth object:

{ "mode": "default" }

or (contractor-run):

{
  "mode": "assume_role",
  "role_arn": "arn:aws:iam::123456789012:role/ContractorAuditReadOnly",
  "external_id": "client-specific-external-id",
  "session_name": "aws-mcp-audit",
  "region_name": "us-east-1"
}

Outputs

Artifacts are stored locally under ./data/snapshots/<snapshot_id>/:

snapshot.json
findings.json
cost.json (tier-1 signals)
cost_explorer.json (if enabled)
report.md / report.pdf

Terraform module (client-side)

See terraform/ContractorAuditReadOnly/ for a simple module that creates a read-only role with ExternalId.

aws-mcp-audit