cloud-audit-mcp

Read-only AWS security-posture checks as Model Context Protocol tools for Claude Desktop, Claude Code and Cursor — with an offline fixture mode that needs no credentials.

Docs and live demo: https://avinash9694.github.io/cloud-audit-mcp/

Install

The server is installed straight from GitHub through npx; nothing to clone or publish. It starts in fixture mode, serving a bundled sample estate so every tool works before you hand it any credentials.

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "cloud-audit": {
      "command": "npx",
      "args": ["-y", "github:Avinash9694/cloud-audit-mcp"],
      "env": { "CLOUD_AUDIT_MODE": "fixture" }
    }
  }
}

Claude Code:

claude mcp add cloud-audit -e CLOUD_AUDIT_MODE=fixture -- npx -y github:Avinash9694/cloud-audit-mcp

Cursor — ~/.cursor/mcp.json or .cursor/mcp.json in a project: same JSON as Claude Desktop.

Pointing it at a real account

Set CLOUD_AUDIT_MODE=aws in the env block. Credentials come from the standard AWS chain (AWS_PROFILE including SSO profiles, AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY, instance or container roles); AWS_REGION picks the region for regional services. The AWS-managed SecurityAudit policy covers every call. If credentials are missing or expired, tools return an error that says how to fix it — the server never crashes.

Then ask: "Run every check and summarise the posture", "Which security groups let the internet reach SSH?", or use the bundled security_review prompt for a full prioritised report.

Related MCP server: infrawise

Why I built this

My day job is a Tauri + React + Rust desktop app that scans AWS and Azure estates, runs compliance checks and hands the results to an AI assistant. The most useful part of that loop is letting the model ask for the next piece of evidence rather than reading a 400-row report. This project distils that into the smallest honest version: a provider interface, a set of checks that are each a tested module, and an MCP surface that is read-only by construction rather than by promise.

Features

• Six tools: whoami, list_checks, run_check, run_all_checks (with a severity floor), describe_resource, summarize_posture (counts, top five risks, a 0–100 score).

• Two resources (audit://checks, audit://fixtures/estate) and one prompt (security_review) that walks the model through a prioritised review.

• Fourteen checks across S3, EC2, RDS, IAM and CloudTrail, each with severity, description, remediation and tests against both a misconfigured and a hardened fixture.

• Read-only, enforced: the AWS provider imports only List*, Describe* and Get* commands, and a unit test fails if any other command name appears in that module. Every tool is annotated readOnlyHint: true.

• Fixture mode for demos, tests and CI: no network, no credentials.

• Structured output: every tool returns a concise markdown summary for the model and a JSON object validated against a Zod output schema.

• Graceful failure: missing credentials, denied permissions and bad fixture files become tool errors with hints; logging is stderr-only so the stdio protocol stays clean.

• Docs site that imports the server's own check catalog and tool manifest, so it cannot drift from the code, plus a terminal demo that runs the real checks in the browser.

Checks

Against the bundled sample estate run_all_checks reports 17 findings (6 critical, 6 high, 3 medium, 2 low) and summarize_posture scores it 42/100 (grade D).

Architecture

 MCP client ──stdio/JSON-RPC──▶ cloud-audit-mcp
 (Claude Desktop, Claude Code,   ├─ tools · resources · prompt   (src/server.ts, src/tools/)
  Cursor)                        ├─ 14 checks                     (src/checks/*.ts)
                                 └─ AuditProvider interface       (src/providers/audit-provider.ts)
                                      ├─ AwsSdkProvider  — SDK v3, List/Describe/Get only
                                      └─ FixtureProvider — fixtures/estate.json

• Checks only ever see AuditProvider; swapping providers is one environment variable.

• withCache memoises each inventory call for 60 s so run_all_checks lists a service once, not once per check.

• defineCheck binds id, severity, title and remediation to every finding so a check module only describes what it saw.

• The posture score starts at 100 and deducts 10/5/2/1 per critical/high/medium/low finding, with repeats of the same severity at half weight.

• docs-site/ depends on the server package (file:..) and renders CHECK_CATALOG and TOOL_MANIFEST directly; a test pins the manifest to the real Zod schemas.

Tech stack

TypeScript (strict, ESM) · @modelcontextprotocol/sdk · Zod · AWS SDK v3 (S3, EC2, IAM, RDS, CloudTrail, STS) · Vitest · ESLint (typescript-eslint, type-checked) · Prettier · GitHub Actions. Docs site: Vite · React 18 · CSS modules · Testing Library.

Running locally

npm install           # also builds dist/ through the prepare script
npm run dev           # start the server over stdio with tsx (fixture mode)
npm run build         # compile to dist/
npm run smoke         # spawn dist/cli.js over stdio, list tools, run every check

cd docs-site
npm install
npm run dev           # docs site on http://localhost:5173/cloud-audit-mcp/

Try the server interactively with the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/cli.js

Testing

npm run lint && npm run typecheck && npm test && npm run smoke   # server
cd docs-site && npm run lint && npm run typecheck && npm test     # docs

The server suite (99 tests) runs every check against both fixtures, exercises each tool through the SDK's in-memory transport, checks provider selection and AWS response normalisation with stubbed clients, and pins the read-only import rule. The docs suite (10 tests) covers the catalog table, install tabs, copy buttons, theme toggle and the in-browser demo.

Project structure

src/
  cli.ts                 stdio entry point (bin: cloud-audit-mcp)
  server.ts              McpServer wiring: tools, resources, prompt, error mapping
  manifest.ts            tool / resource / prompt docs shared with the site
  posture.ts             scoring, ordering, severity filters
  checks/                one module per check + index/catalog
  providers/             AuditProvider, AwsSdkProvider, FixtureProvider, cache, selection
  resources/             describe-resource lookup
  tools/                 zod schemas, handlers, markdown formatting
  __tests__/             vitest suites
fixtures/                estate.json (misconfigured) and clean-estate.json (hardened)
scripts/smoke.mjs        end-to-end stdio smoke test
docs-site/               Vite + React docs, deployed to GitHub Pages
.github/workflows/       deploy.yml (gates + Pages), ci.yml (Node 20 and 22)

Roadmap and known limitations

• Azure and GCP providers behind the same AuditProvider interface.

• More checks: IAM password policy, S3 access logging, unused security groups, RDS backup retention.

• aws mode queries one region per process; multi-region sweeps mean running it once per AWS_REGION.

• IAM access-key age uses creation date, not last rotation, which is what IAM exposes.

• The posture score is a triage aid, not a compliance number.

License

MIT