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_idrun_checks(snapshot_id) -> finding_set_idcost_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.jsonfindings.jsoncost.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.