# 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)
```bash
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:
```json
{
"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:
```json
{ "mode": "default" }
```
or (contractor-run):
```json
{
"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.
