# I Built an MCP Server That Investigates Your AWS Bill

I Built an MCP Server That Investigates Your AWS Bill

TL;DR: Install one MCP server → ask your AI "why did my bill spike?" → get a full investigation with resource IDs, dollar amounts, and CLI commands to fix it. Open source, 8 tools, works with Kiro, Claude Code, and Cursor.

The Problem Every Cloud Engineer Knows

Every month, the same ritual. You open AWS Cost Explorer, click through dashboards, squint at bar charts, try to figure out what changed. Then you open EC2 to check for idle instances. Then you check tags — half your resources don't have them. Then you wonder if someone left a NAT Gateway running in a sandbox account.

This process takes 30-60 minutes. And you do it every month. Sometimes every week when something spikes.

I've been building cloud architectures for years, and this friction never went away. The data is there — Cost Explorer has it, CloudWatch has it, the Tagging API has it. But the workflow of pulling it all together, correlating it, and turning it into actionable recommendations? That's still manual.

What if your AI assistant could do all of that in one question?

That's what I built.

The Solution: byaml-finops-mcp

pip install byaml-finops-mcp

It's an MCP server — a standard protocol that lets AI assistants call external tools. Once installed, your AI (Kiro, Claude Code, Cursor, or any MCP-compatible client) gains 8 new capabilities that connect directly to your AWS account:

Tool	What it does
`get_cost_by_service`	Monthly costs by service, current vs previous month
`get_cost_anomalies`	Detected cost spikes with root causes
`find_idle_resources`	EC2 with <5% CPU, unattached EBS volumes
`estimate_termination_savings`	Exact monthly savings from terminating instances
`get_savings_recommendations`	Rightsizing + Savings Plans
`detect_missing_tags`	Resources missing owner/env/costCenter tags
`generate_byaml_from_account`	Scan account → generate architecture-as-code
`validate_byaml`	Validate architecture files against schema + policies

The key insight: your AI doesn't just answer questions about costs — it investigates them. It pulls data from multiple AWS APIs, correlates findings, and gives you specific resource IDs with dollar amounts and CLI commands to fix issues.

Real Results From My Account

I didn't build this with mock data. I ran it against my own AWS account — the one running my side projects, APIs, and experiments. Here's what it found in seconds:

Missing Tags: 46/46 resources non-compliant

Resources scanned: 46
Violations: 46 (100% non-compliant)
Required tags missing: owner, env, costCenter

Every single resource — Lambda functions, S3 buckets, API Gateways, CloudFront distributions — was missing the required governance tags. But here's the interesting part: the tool identified a case mismatch issue. Many resources had Owner and Environment (capitalized) but the policy requires lowercase owner and env. A subtle bug that would take forever to find manually.

Architecture Discovery: 27 components auto-detected

The generate_byaml_from_account tool scanned 7 AWS services (Lambda, S3, DynamoDB, API Gateway, CloudFront, RDS, EC2) and generated a complete architecture file:

byamlVersion: '0.3'
architecture:
  id: aws-us-east-1
  environment: prod
  cloudProvider: aws
components:
- id: byaml-schema-api-api
  type: aws.lambda
  props:
    runtime: python3.11
    memory: 256
- id: byaml-schema-registry
  type: aws.s3
# ... 25 more components

27 components discovered, mapped to typed BYaML component types, and output as a valid .byaml file. This is architecture-as-code generated from your live infrastructure — not from Terraform or CloudFormation, but from what's actually running.

Validation: Zero errors on generated output

{
  "valid": true,
  "findings": [],
  "summary": {"errors": 0, "warnings": 0, "total": 0}
}

The generated file validates cleanly against the v0.3 JSON Schema, a component catalog (13 valid types), and FinOps policy rules. If you add a component with a type that doesn't exist in the catalog, you get a warning. If you're missing required fields, you get an error. All in real-time.

How It Works

The architecture is intentionally simple:

Your AI (Kiro / Claude Code / Cursor)
        ↓ MCP Protocol (stdio)
byaml-finops-mcp (runs on your machine)
        ↓ boto3 (AWS SDK)
Your AWS Account (read-only API calls)
        ↓
Cost Explorer, EC2, CloudWatch, Lambda, S3, RDS, DynamoDB, Tagging API

Three design principles:

Local-first — the server runs on your machine. No data leaves your environment. No SaaS dashboard, no third-party ingestion.
Read-only — it never modifies your AWS resources. Only Describe*, List*, and Get* API calls.
Zero config — it uses your existing AWS CLI profile. If aws sts get-caller-identity works, the MCP server works.

Install in 2 Minutes

1. Install

pip install byaml-finops-mcp

Or with uvx (no install needed):

uvx byaml-finops-mcp

2. Configure your MCP client

Kiro (.kiro/settings/mcp.json):

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

Claude Code (~/.claude/mcp.json) and Cursor use the same format.

3. Ask your AI

"Why did my AWS bill spike this month?"

"Find idle resources and tell me how much I'd save by terminating them"

"Which resources are missing governance tags?"

"Generate a BYaML architecture file from my account"

The AI will call the appropriate tools, correlate the results, and give you a structured investigation with actionable next steps.

The BYaML Connection

The last two tools (generate_byaml_from_account and validate_byaml) connect to BYaML — an architecture-as-code format I'm building at Brickstore AI. Think of it as "OpenAPI spec, but for cloud architectures."

The schema is fully public:

schema.byaml.org/v1/byaml/schema/version/0.3 — JSON Schema
schema.byaml.org/v1/byaml/schema/version/0.3/catalog — Valid component types
schema.byaml.org/v1/byaml/schema/version/0.3/policies — FinOps policy rules
schema.byaml.org/v1/byaml/schema/version/0.3/relationships — Valid connections between components

The MCP server fetches the schema from this public API and validates locally. No API key needed. There's also a VS Code extension (brickstore-ai.byaml) that gives you syntax highlighting, autocomplete, and real-time validation for .byaml files.

The Backstory

This project evolved from a series of experiments I did with NVIDIA NIM + FinOps agents. The original version used mock billing data and a single-agent architecture. Then I rebuilt it with sub-agents (cost analyst, resource auditor, deploy correlator). Then I realized: the real value isn't in the agent framework — it's in the tools.

MCP gave me the perfect distribution mechanism. Instead of building a full agent that only works with one LLM, I built tools that work with any AI that speaks MCP. The intelligence comes from the AI client; the data comes from the tools.

What's Next

Terraform Connector — generate BYaML from tfplan.json (biggest gap for enterprise)
Drift Engine — compare your .byaml file against what's actually running in AWS
Multi-account — cross-account cost analysis via AWS Organizations
Premium tier — historical trends, AI-powered root cause analysis, architecture intelligence via api.dev.brickstore.ai