byaml-finops-mcp

An MCP server that gives your AI assistant the ability to investigate AWS costs, find waste, recommend savings, and generate architecture-as-code — using your own AWS account data.

Ask your AI: "Why did my AWS bill spike this month?" and get a full investigation with resource IDs, root causes, and CLI commands to fix it.

Tools

Install

Option A: uvx (recommended)

uvx byaml-finops-mcp

Option B: pip

pip install byaml-finops-mcp

Configure

Kiro

Add to .kiro/settings/mcp.json:

{
  "mcpServers": {
    "byaml-finops": {
      "command": "uvx",
      "args": ["byaml-finops-mcp"],
      "env": {
        "AWS_PROFILE": "your-profile"
      }
    }
  }
}

Claude Code

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "byaml-finops": {
      "command": "uvx",
      "args": ["byaml-finops-mcp"],
      "env": {
        "AWS_PROFILE": "your-profile"
      }
    }
  }
}

Cursor

Add to MCP settings:

{
  "byaml-finops": {
    "command": "uvx",
    "args": ["byaml-finops-mcp"],
    "env": {
      "AWS_PROFILE": "your-profile"
    }
  }
}

Prerequisites

1. AWS CLI configured (aws configure or aws sso login)
2. uv installed (docs)
3. IAM permissions — read-only access:

{
  "Effect": "Allow",
  "Action": [
    "ce:GetCostAndUsage",
    "ce:GetAnomalies",
    "ce:GetRightsizingRecommendation",
    "ec2:DescribeInstances",
    "ec2:DescribeVolumes",
    "cloudwatch:GetMetricStatistics",
    "tag:GetResources",
    "savingsplans:DescribeSavingsPlans",
    "lambda:ListFunctions",
    "s3:ListBuckets",
    "dynamodb:ListTables",
    "apigateway:GetRestApis",
    "cloudfront:ListDistributions",
    "rds:DescribeDBInstances"
  ],
  "Resource": "*"
}

Usage

Once configured, just ask your AI:

• "Why did my AWS bill spike this month?"
• "Find idle resources in my account"
• "Which resources are missing tags?"
• "How much would I save by terminating these instances?"
• "Generate a BYaML architecture file from my account"
• "Validate this BYaML file"

How it works

Your AI (Kiro / Claude Code / Cursor)
        ↓ MCP Protocol
byaml-finops-mcp server (runs locally)
        ↓ boto3
Your AWS Account (read-only)
        ↓
Cost Explorer, EC2, CloudWatch, Lambda, S3, RDS, DynamoDB

• Local-first — runs on your machine, no data leaves your environment
• Read-only — never modifies your AWS resources
• Zero config — uses your existing AWS CLI profile

BYaML Integration

This server can generate and validate BYaML architecture files:

• generate_byaml_from_account scans your AWS resources and produces a .byaml file
• validate_byaml checks your .byaml file against the v0.3 schema, component catalog, and FinOps policy rules
• Schema is fetched from schema.byaml.org (public API, no auth required)

Security

• No credentials are stored by this tool
• Uses your local AWS CLI profile/SSO session
• All API calls are read-only
• No data is sent to any third party
• Schema validation fetches from schema.byaml.org (public, read-only)

Built by

Brickstore AI — AI-native cloud architecture platform

License

MIT