aws-resiliency-mcp

MCP server that evaluates AWS account resiliency posture and identifies disaster recovery gaps across 12 service categories.

Features

• 17 MCP Tools — granular per-category assessments plus discovery, cross-region, multi-AZ, and full-scan tools
• 12 Assessment Categories — compute, data, networking, output, serverless, AI/ML, containers, security, analytics, storage, messaging, observability
• Discovery-First Architecture — auto-detects active services via Resource Explorer / Config before assessing
• Multi-Region Scanning — parallel cross-region DR gap analysis across 10+ regions
• Environment Classification — auto-tags resources as production/DR/non-prod from tags and naming patterns
• Region Role Detection — classifies regions as PRIMARY, DR/SECONDARY, or NOT_USED
• 4 Output Formats — Markdown, HTML, DOCX, PDF
• Cross-Account Access — supports STS AssumeRole and temporary credentials
• Severity Adjustment — automatically bumps production findings up, non-prod findings down
• Parallel Execution — concurrent assessments and region scans via asyncio thread pool

Installation

# Recommended: run directly with uvx
uvx aws-resiliency-mcp

# Or install via pip
pip install aws-resiliency-mcp

# Development install
pip install -e ".[dev]"

Quick Start

Claude Desktop / Amazon Quick

Add to your MCP client configuration:

{
  "mcpServers": {
    "aws-resiliency-mcp": {
      "command": "uvx",
      "args": ["aws-resiliency-mcp"],
      "env": {
        "AWS_PROFILE": "default",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

With Docker

{
  "mcpServers": {
    "aws-resiliency-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "AWS_ACCESS_KEY_ID",
        "-e", "AWS_SECRET_ACCESS_KEY",
        "-e", "AWS_SESSION_TOKEN",
        "aws-resiliency-mcp"
      ]
    }
  }
}

Tool Reference

Architecture

┌─────────────┐     ┌──────────────┐     ┌────────────────┐     ┌────────────┐
│  Discovery  │────▶│   Assess     │────▶│   Classify     │────▶│   Format   │
│             │     │  (parallel)  │     │  (env + region)│     │ (md/html/  │
│ RE2/Config/ │     │  12 modules  │     │  severity adj  │     │  docx/pdf) │
│ describe    │     │  per-service │     │  region roles  │     │            │
└─────────────┘     └──────────────┘     └────────────────┘     └────────────┘

1. Discover — Identify which services have resources (skip empty categories)
2. Assess — Run category-specific checks in parallel threads
3. Classify — Tag each finding with environment context, adjust severity
4. Format — Generate report in requested format with prioritized recommendations

Configuration

Credentials

The server uses the standard AWS credential chain:

1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN)
2. AWS profiles (AWS_PROFILE)
3. Instance metadata / container credentials
4. SSO credentials

Cross-Account Access

Provide an account_id parameter to any tool — the server will AssumeRole to arn:aws:iam::{account_id}:role/ReadOnlyAccess.

Alternatively, pass temporary credentials directly:

assess_compute_resiliency(
    region="us-east-1",
    account_id="123456789012",
    access_key_id="ASIA...",
    secret_access_key="...",
    session_token="..."
)

Environment Variables

Output Formats

All formats include: summary metrics, DR readiness, tagging context, region strategy, per-category findings sorted by environment priority, and prioritized action items.

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run unit tests
pytest

# Run with coverage
pytest --cov=aws_resiliency_mcp --cov-report=term-missing

# Run integration tests (requires AWS credentials)
pytest -m integration

# Lint and format
ruff check src/ tests/
ruff format src/ tests/

# Type check
mypy src/

# Install pre-commit hooks
pre-commit install

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Install dev dependencies (pip install -e ".[dev]")
4. Make changes and add tests
5. Ensure all checks pass (pre-commit run --all-files)
6. Commit (git commit -m 'Add amazing feature')
7. Push and open a Pull Request

Guidelines

• All new assessment modules must include unit tests with mocked boto3 calls
• Maintain 80%+ test coverage
• Follow existing patterns for Finding creation and environment enrichment
• Use ruff for formatting (enforced via pre-commit)

License

This project is licensed under the MIT License — see the LICENSE file for details.