Metadata-Version: 2.4
Name: byaml-finops-mcp
Version: 0.1.0
Summary: MCP server for AWS FinOps analysis — cost investigation, idle resources, savings recommendations, and BYaML architecture generation
Project-URL: Homepage, https://github.com/brickstore-ai/byaml-finops-mcp
Project-URL: Documentation, https://schema.byaml.org
Project-URL: Issues, https://github.com/brickstore-ai/byaml-finops-mcp/issues
Author-email: Carlos Cortez <carlos@byaml.ai>
License: MIT
License-File: LICENSE
Keywords: architecture,aws,byaml,cost-optimization,finops,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Requires-Dist: boto3>=1.43.17
Requires-Dist: jsonschema>=4.20.0
Requires-Dist: mcp>=1.27.1
Requires-Dist: pyyaml>=6.0.3
Description-Content-Type: text/markdown

# 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.

<!-- ![Demo](demo.gif) -->

## Tools

| 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 and impact |
| `find_idle_resources` | EC2 instances with <5% CPU, unattached EBS volumes |
| `get_savings_recommendations` | Rightsizing + Savings Plans recommendations |
| `detect_missing_tags` | Resources missing required tags (owner, env, costCenter) |
| `estimate_termination_savings` | Calculate exact monthly savings from terminating instances |
| `generate_byaml_from_account` | Scan AWS account → generate BYaML v0.3 architecture file |
| `validate_byaml` | Validate BYaML against schema + component catalog + policy rules |

## Install

### Option A: uvx (recommended)

```bash
uvx byaml-finops-mcp
```

### Option B: pip

```bash
pip install byaml-finops-mcp
```

## Configure

### Kiro

Add to `.kiro/settings/mcp.json`:

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

### Claude Code

Add to `~/.claude/mcp.json`:

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

### Cursor

Add to MCP settings:

```json
{
  "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](https://docs.astral.sh/uv/getting-started/installation/))
3. **IAM permissions** — read-only access:

```json
{
  "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](https://schema.byaml.org) 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](https://byaml.ai) — AI-native cloud architecture platform

## License

MIT
