finops-mcp 0.3.0__tar.gz

finops_mcp-0.3.0/.env.example

@@ -0,0 +1,74 @@
+# ══════════════════════════════════════════════════════════════════════════════
+# FinOps MCP — Environment Variables
+# Copy to .env and fill in the credentials for the providers you use.
+# Unconfigured providers are silently skipped.
+# ══════════════════════════════════════════════════════════════════════════════
+
+# ── AWS ────────────────────────────────────────────────────────────────────────
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+AWS_DEFAULT_REGION=us-east-1
+# Multi-account: comma-separated IAM role ARNs to assume
+# AWS_ROLE_ARNS=arn:aws:iam::111111111111:role/FinOps,arn:aws:iam::222222222222:role/FinOps
+
+# ── Azure ──────────────────────────────────────────────────────────────────────
+AZURE_CLIENT_ID=
+AZURE_CLIENT_SECRET=
+AZURE_TENANT_ID=
+AZURE_SUBSCRIPTION_IDS=         # comma-separated
+
+# ── GCP ────────────────────────────────────────────────────────────────────────
+GCP_SERVICE_ACCOUNT_KEY_PATH=
+GCP_BILLING_ACCOUNT_IDS=        # format: XXXXXX-XXXXXX-XXXXXX, comma-separated
+# Optional: BigQuery billing export table for full granularity
+# GCP_BQ_BILLING_TABLE=myproject.my_dataset.gcp_billing_export_v1_XXXXXX
+
+# ── Datadog ────────────────────────────────────────────────────────────────────
+DATADOG_API_KEY=
+DATADOG_APP_KEY=
+# DATADOG_SITE=datadoghq.com    # use datadoghq.eu for EU
+
+# ── Snowflake ──────────────────────────────────────────────────────────────────
+SNOWFLAKE_ACCOUNT=              # e.g. xy12345.us-east-1
+SNOWFLAKE_USER=
+SNOWFLAKE_PASSWORD=
+SNOWFLAKE_WAREHOUSE=            # optional, uses default if unset
+SNOWFLAKE_ROLE=ACCOUNTADMIN
+# SNOWFLAKE_PRIVATE_KEY_PATH=   # alternative to password auth
+# SNOWFLAKE_CREDIT_PRICE=3.00   # USD per credit (override if on a committed contract)
+
+# ── GitHub ─────────────────────────────────────────────────────────────────────
+GITHUB_TOKEN=                   # fine-grained PAT with read:org and read:billing
+GITHUB_ORGS=                    # comma-separated org names
+
+# ── Stripe ─────────────────────────────────────────────────────────────────────
+STRIPE_SECRET_KEY=              # sk_live_...
+
+# ── MongoDB Atlas ──────────────────────────────────────────────────────────────
+MONGODB_ATLAS_PUBLIC_KEY=
+MONGODB_ATLAS_PRIVATE_KEY=
+MONGODB_ATLAS_ORG_IDS=         # comma-separated org IDs
+
+# ── Vercel ─────────────────────────────────────────────────────────────────────
+VERCEL_TOKEN=
+VERCEL_TEAM_ID=                 # optional, leave blank for personal accounts
+
+# ── Cloudflare ─────────────────────────────────────────────────────────────────
+CLOUDFLARE_API_TOKEN=
+CLOUDFLARE_ACCOUNT_ID=
+
+# ── PagerDuty ──────────────────────────────────────────────────────────────────
+PAGERDUTY_API_KEY=
+# PAGERDUTY_PRICE_PER_USER=21.00  # override if on a negotiated contract
+
+# ── Twilio ─────────────────────────────────────────────────────────────────────
+TWILIO_ACCOUNT_SID=
+TWILIO_AUTH_TOKEN=
+
+# ── New Relic ──────────────────────────────────────────────────────────────────
+NEW_RELIC_API_KEY=              # User API key (NRAK-...)
+NEW_RELIC_ACCOUNT_ID=
+# NEW_RELIC_INGEST_PRICE_PER_GB=0.35  # override if on a negotiated contract
+
+# ── General ────────────────────────────────────────────────────────────────────
+DEFAULT_LOOKBACK_DAYS=30

finops_mcp-0.3.0/.gitignore

@@ -0,0 +1,51 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Environment & secrets — NEVER commit these
+.env
+*.env
+.env.local
+.env.*.local
+finops_vault.db
+finops.db
+*.db
+*.sqlite
+
+# Credentials & keys
+*.pem
+*.key
+*.p12
+*.pfx
+service_account*.json
+*credentials*.json
+
+# Claude / MCP local state
+.claude/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Logs
+*.log
+logs/

finops_mcp-0.3.0/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: finops-mcp
+Version: 0.3.0
+Summary: Headless FinOps MCP server — cloud + SaaS cost intelligence for Claude
+Requires-Python: >=3.10
+Requires-Dist: apscheduler>=3.10.0
+Requires-Dist: azure-identity>=1.15.0
+Requires-Dist: azure-mgmt-costmanagement>=4.0.0
+Requires-Dist: boto3>=1.34.0
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: google-cloud-bigquery>=3.17.0
+Requires-Dist: google-cloud-billing>=1.13.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.3.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: sqlalchemy>=2.0.0
+Provides-Extra: azure-oauth
+Requires-Dist: msal>=1.28.0; extra == 'azure-oauth'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: keyring
+Requires-Dist: keyring>=25.0.0; extra == 'keyring'
+Provides-Extra: pdf
+Requires-Dist: pdfplumber>=0.10.0; extra == 'pdf'
+Provides-Extra: snowflake
+Requires-Dist: snowflake-connector-python>=3.6.0; extra == 'snowflake'

finops_mcp-0.3.0/claude_mcp_config.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "finops": {
+      "command": "/Users/chandan/finops/.venv/bin/python",
+      "args": ["-m", "finops.server"],
+      "cwd": "/Users/chandan/finops",
+      "env": {
+        "AWS_DEFAULT_REGION": "us-east-1"
+      }
+    }
+  }
+}

finops_mcp-0.3.0/finopsmcp/.env.example

@@ -0,0 +1,74 @@
+# ══════════════════════════════════════════════════════════════════════════════
+# FinOps MCP — Environment Variables
+# Copy to .env and fill in the credentials for the providers you use.
+# Unconfigured providers are silently skipped.
+# ══════════════════════════════════════════════════════════════════════════════
+
+# ── AWS ────────────────────────────────────────────────────────────────────────
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+AWS_DEFAULT_REGION=us-east-1
+# Multi-account: comma-separated IAM role ARNs to assume
+# AWS_ROLE_ARNS=arn:aws:iam::111111111111:role/FinOps,arn:aws:iam::222222222222:role/FinOps
+
+# ── Azure ──────────────────────────────────────────────────────────────────────
+AZURE_CLIENT_ID=
+AZURE_CLIENT_SECRET=
+AZURE_TENANT_ID=
+AZURE_SUBSCRIPTION_IDS=         # comma-separated
+
+# ── GCP ────────────────────────────────────────────────────────────────────────
+GCP_SERVICE_ACCOUNT_KEY_PATH=
+GCP_BILLING_ACCOUNT_IDS=        # format: XXXXXX-XXXXXX-XXXXXX, comma-separated
+# Optional: BigQuery billing export table for full granularity
+# GCP_BQ_BILLING_TABLE=myproject.my_dataset.gcp_billing_export_v1_XXXXXX
+
+# ── Datadog ────────────────────────────────────────────────────────────────────
+DATADOG_API_KEY=
+DATADOG_APP_KEY=
+# DATADOG_SITE=datadoghq.com    # use datadoghq.eu for EU
+
+# ── Snowflake ──────────────────────────────────────────────────────────────────
+SNOWFLAKE_ACCOUNT=              # e.g. xy12345.us-east-1
+SNOWFLAKE_USER=
+SNOWFLAKE_PASSWORD=
+SNOWFLAKE_WAREHOUSE=            # optional, uses default if unset
+SNOWFLAKE_ROLE=ACCOUNTADMIN
+# SNOWFLAKE_PRIVATE_KEY_PATH=   # alternative to password auth
+# SNOWFLAKE_CREDIT_PRICE=3.00   # USD per credit (override if on a committed contract)
+
+# ── GitHub ─────────────────────────────────────────────────────────────────────
+GITHUB_TOKEN=                   # fine-grained PAT with read:org and read:billing
+GITHUB_ORGS=                    # comma-separated org names
+
+# ── Stripe ─────────────────────────────────────────────────────────────────────
+STRIPE_SECRET_KEY=              # sk_live_...
+
+# ── MongoDB Atlas ──────────────────────────────────────────────────────────────
+MONGODB_ATLAS_PUBLIC_KEY=
+MONGODB_ATLAS_PRIVATE_KEY=
+MONGODB_ATLAS_ORG_IDS=         # comma-separated org IDs
+
+# ── Vercel ─────────────────────────────────────────────────────────────────────
+VERCEL_TOKEN=
+VERCEL_TEAM_ID=                 # optional, leave blank for personal accounts
+
+# ── Cloudflare ─────────────────────────────────────────────────────────────────
+CLOUDFLARE_API_TOKEN=
+CLOUDFLARE_ACCOUNT_ID=
+
+# ── PagerDuty ──────────────────────────────────────────────────────────────────
+PAGERDUTY_API_KEY=
+# PAGERDUTY_PRICE_PER_USER=21.00  # override if on a negotiated contract
+
+# ── Twilio ─────────────────────────────────────────────────────────────────────
+TWILIO_ACCOUNT_SID=
+TWILIO_AUTH_TOKEN=
+
+# ── New Relic ──────────────────────────────────────────────────────────────────
+NEW_RELIC_API_KEY=              # User API key (NRAK-...)
+NEW_RELIC_ACCOUNT_ID=
+# NEW_RELIC_INGEST_PRICE_PER_GB=0.35  # override if on a negotiated contract
+
+# ── General ────────────────────────────────────────────────────────────────────
+DEFAULT_LOOKBACK_DAYS=30

finops_mcp-0.3.0/finopsmcp/.gitignore

@@ -0,0 +1,51 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Environment & secrets — NEVER commit these
+.env
+*.env
+.env.local
+.env.*.local
+finops_vault.db
+finops.db
+*.db
+*.sqlite
+
+# Credentials & keys
+*.pem
+*.key
+*.p12
+*.pfx
+service_account*.json
+*credentials*.json
+
+# Claude / MCP local state
+.claude/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Logs
+*.log
+logs/

finops_mcp-0.3.0/finopsmcp/claude_mcp_config.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "finops": {
+      "command": "/Users/chandan/finops/.venv/bin/python",
+      "args": ["-m", "finops.server"],
+      "cwd": "/Users/chandan/finops",
+      "env": {
+        "AWS_DEFAULT_REGION": "us-east-1"
+      }
+    }
+  }
+}

finops_mcp-0.3.0/finopsmcp/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "finops-mcp"
+version = "0.3.0"
+description = "Headless FinOps MCP server — cloud + SaaS cost intelligence for Claude"
+requires-python = ">=3.10"
+dependencies = [
+    "mcp[cli]>=1.3.0",
+    # cloud providers
+    "boto3>=1.34.0",
+    "azure-mgmt-costmanagement>=4.0.0",
+    "azure-identity>=1.15.0",
+    "google-cloud-billing>=1.13.0",
+    "google-cloud-bigquery>=3.17.0",
+    # storage + scheduling
+    "sqlalchemy>=2.0.0",
+    "apscheduler>=3.10.0",
+    # security
+    "cryptography>=42.0.0",
+    # shared utilities
+    "python-dotenv>=1.0.0",
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+    "pyyaml>=6.0.0",
+]
+
+[project.optional-dependencies]
+snowflake = ["snowflake-connector-python>=3.6.0"]
+azure-oauth = ["msal>=1.28.0"]
+keyring = ["keyring>=25.0.0"]
+pdf = ["pdfplumber>=0.10.0"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "ruff>=0.4"]
+
+[project.scripts]
+finops-mcp   = "finops.server:main"
+finops       = "finops.setup_wizard:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/finops"]
+
+[tool.ruff]
+line-length = 100

finops_mcp-0.3.0/finopsmcp/src/finops/anomaly/detector.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import statistics
+from dataclasses import dataclass, field
+from datetime import date, datetime, timezone
+from typing import Any
+
+from sqlalchemy import and_, select
+
+from ..storage.db import anomalies, get_engine
+from ..storage.snapshots import get_history
+
+_MIN_HISTORY_DAYS = 7      # need at least 7 data points
+_MIN_SPEND_THRESHOLD = 5.0  # ignore noise below $5
+_Z_SCORE_THRESHOLD = 2.0   # flag if |z| > 2.0
+_PCT_THRESHOLD = 20.0       # AND |pct_change| > 20%
+
+
+@dataclass
+class AnomalyResult:
+    provider: str
+    service: str
+    account_id: str
+    snapshot_date: date
+    severity: str           # "high" | "medium" | "low"
+    direction: str          # "spike" | "drop"
+    pct_change: float
+    z_score: float
+    baseline_mean: float
+    current_amount: float
+    is_new: bool = True
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def summary(self) -> str:
+        arrow = "↑" if self.direction == "spike" else "↓"
+        return (
+            f"{self.provider.upper()} / {self.service}: "
+            f"{arrow} {abs(self.pct_change):.0f}% vs 28-day baseline "
+            f"(${self.current_amount:,.2f} vs avg ${self.baseline_mean:,.2f}) "
+            f"[{self.severity.upper()}]"
+        )
+
+
+def _severity(z: float, pct: float) -> str:
+    az, ap = abs(z), abs(pct)
+    if az >= 3.5 or ap >= 100:
+        return "high"
+    if az >= 2.5 or ap >= 50:
+        return "medium"
+    return "low"
+
+
+def detect_for_series(
+    provider: str,
+    service: str,
+    account_id: str,
+    snapshot_date: date,
+    current_amount: float,
+    history_amounts: list[float],
+) -> AnomalyResult | None:
+    if len(history_amounts) < _MIN_HISTORY_DAYS:
+        return None
+    if current_amount < _MIN_SPEND_THRESHOLD and max(history_amounts, default=0) < _MIN_SPEND_THRESHOLD:
+        return None
+
+    mean = statistics.mean(history_amounts)
+    if mean < _MIN_SPEND_THRESHOLD:
+        return None
+
+    stdev = statistics.stdev(history_amounts) if len(history_amounts) > 1 else 0.0
+    z_score = (current_amount - mean) / stdev if stdev > 0 else 0.0
+    pct_change = (current_amount - mean) / mean * 100
+
+    if abs(z_score) < _Z_SCORE_THRESHOLD or abs(pct_change) < _PCT_THRESHOLD:
+        return None
+
+    return AnomalyResult(
+        provider=provider,
+        service=service,
+        account_id=account_id,
+        snapshot_date=snapshot_date,
+        severity=_severity(z_score, pct_change),
+        direction="spike" if pct_change > 0 else "drop",
+        pct_change=round(pct_change, 2),
+        z_score=round(z_score, 3),
+        baseline_mean=round(mean, 4),
+        current_amount=round(current_amount, 4),
+    )
+
+
+def detect_from_snapshot(
+    provider: str,
+    service: str,
+    account_id: str,
+    snapshot_date: date,
+    current_amount: float,
+    lookback_days: int = 28,
+) -> AnomalyResult | None:
+    history = get_history(provider, service, account_id, days=lookback_days)
+    today_iso = snapshot_date.isoformat()
+    amounts = [
+        row["amount_usd"]
+        for row in history
+        if row["snapshot_date"] != today_iso and row["amount_usd"] > 0
+    ]
+    return detect_for_series(provider, service, account_id, snapshot_date, current_amount, amounts)
+
+
+def persist_anomaly(result: AnomalyResult) -> int:
+    engine = get_engine()
+    with engine.begin() as conn:
+        r = conn.execute(
+            anomalies.insert().values(
+                provider=result.provider,
+                service=result.service,
+                account_id=result.account_id,
+                detected_at=datetime.now(timezone.utc),
+                snapshot_date=result.snapshot_date.isoformat(),
+                severity=result.severity,
+                direction=result.direction,
+                pct_change=result.pct_change,
+                z_score=result.z_score,
+                baseline_mean=result.baseline_mean,
+                current_amount=result.current_amount,
+                acknowledged=False,
+                notified=False,
+            )
+        )
+        return r.lastrowid  # type: ignore[return-value]
+
+
+def get_active_anomalies(
+    provider: str | None = None,
+    severity: str | None = None,
+    limit: int = 50,
+) -> list[dict[str, Any]]:
+    engine = get_engine()
+    query = (
+        select(anomalies)
+        .where(anomalies.c.acknowledged == False)  # noqa: E712
+        .order_by(anomalies.c.detected_at.desc())
+        .limit(limit)
+    )
+    if provider:
+        query = query.where(anomalies.c.provider == provider)
+    if severity:
+        query = query.where(anomalies.c.severity == severity)
+    with engine.connect() as conn:
+        return [dict(r._mapping) for r in conn.execute(query).fetchall()]
+
+
+def acknowledge_anomaly(anomaly_id: int) -> bool:
+    engine = get_engine()
+    with engine.begin() as conn:
+        result = conn.execute(
+            anomalies.update()
+            .where(anomalies.c.id == anomaly_id)
+            .values(acknowledged=True)
+        )
+        return result.rowcount > 0
+
+
+def mark_notified(anomaly_id: int) -> None:
+    engine = get_engine()
+    with engine.begin() as conn:
+        conn.execute(
+            anomalies.update()
+            .where(anomalies.c.id == anomaly_id)
+            .values(notified=True)
+        )

finops_mcp-0.3.0/finopsmcp/src/finops/anomaly/seasonality.py

@@ -0,0 +1,131 @@
+"""
+Seasonality-aware anomaly detection.
+
+Compares today against the same weekday over the prior N weeks, not a flat
+rolling mean. This eliminates false positives from weekly patterns (e.g.
+Monday batch jobs, weekend traffic drops) that naive z-score flags as anomalies.
+
+Strategy:
+  1. Same-weekday baseline: compare Monday vs last 4 Mondays, etc.
+  2. If not enough same-weekday points, fall back to rolling-mean detection.
+  3. Combine both signals — flag only when both agree (reduces false positives).
+"""
+from __future__ import annotations
+
+import statistics
+from datetime import date, timedelta
+from typing import Any
+
+from .detector import (
+    AnomalyResult,
+    _MIN_HISTORY_DAYS,
+    _MIN_SPEND_THRESHOLD,
+    _PCT_THRESHOLD,
+    _Z_SCORE_THRESHOLD,
+    _severity,
+    detect_for_series,
+)
+from ..storage.snapshots import get_history
+
+_MIN_SAME_WEEKDAY_POINTS = 3  # need at least 3 same-weekday readings
+
+
+def _same_weekday_amounts(
+    history: list[dict[str, Any]],
+    target_weekday: int,  # 0=Monday … 6=Sunday
+    current_date_iso: str,
+) -> list[float]:
+    """Return amounts from history rows that fall on target_weekday, excluding today."""
+    out: list[float] = []
+    for row in history:
+        if row["snapshot_date"] == current_date_iso:
+            continue
+        try:
+            d = date.fromisoformat(row["snapshot_date"])
+        except ValueError:
+            continue
+        if d.weekday() == target_weekday and row["amount_usd"] > 0:
+            out.append(row["amount_usd"])
+    return out
+
+
+def detect_with_seasonality(
+    provider: str,
+    service: str,
+    account_id: str,
+    snapshot_date: date,
+    current_amount: float,
+    lookback_days: int = 56,  # 8 weeks — enough for 8 same-weekday samples
+) -> AnomalyResult | None:
+    """
+    Seasonality-aware detection. Lookback extended to 56 days (8 weeks) to
+    collect enough same-weekday readings; falls back to rolling mean if sparse.
+    """
+    if current_amount < _MIN_SPEND_THRESHOLD:
+        return None
+
+    history = get_history(provider, service, account_id, days=lookback_days)
+    today_iso = snapshot_date.isoformat()
+    weekday = snapshot_date.weekday()
+
+    same_day_amounts = _same_weekday_amounts(history, weekday, today_iso)
+
+    if len(same_day_amounts) >= _MIN_SAME_WEEKDAY_POINTS:
+        result = _detect_against_baseline(
+            provider, service, account_id, snapshot_date, current_amount,
+            same_day_amounts, baseline_label="same-weekday"
+        )
+        if result is not None:
+            result.metadata["detection_method"] = "seasonality-aware (same-weekday)"
+            result.metadata["weekday_samples"] = len(same_day_amounts)
+        return result
+    else:
+        # Fallback: classic rolling-mean (28-day)
+        rolling_amounts = [
+            row["amount_usd"]
+            for row in history
+            if row["snapshot_date"] != today_iso and row["amount_usd"] > 0
+        ]
+        result = detect_for_series(
+            provider, service, account_id, snapshot_date,
+            current_amount, rolling_amounts
+        )
+        if result is not None:
+            result.metadata["detection_method"] = "rolling-mean (insufficient same-weekday data)"
+            result.metadata["weekday_samples"] = len(same_day_amounts)
+        return result
+
+
+def _detect_against_baseline(
+    provider: str,
+    service: str,
+    account_id: str,
+    snapshot_date: date,
+    current_amount: float,
+    baseline_amounts: list[float],
+    baseline_label: str,
+) -> AnomalyResult | None:
+    mean = statistics.mean(baseline_amounts)
+    if mean < _MIN_SPEND_THRESHOLD:
+        return None
+
+    stdev = statistics.stdev(baseline_amounts) if len(baseline_amounts) > 1 else 0.0
+    z_score = (current_amount - mean) / stdev if stdev > 0 else 0.0
+    pct_change = (current_amount - mean) / mean * 100
+
+    if abs(z_score) < _Z_SCORE_THRESHOLD or abs(pct_change) < _PCT_THRESHOLD:
+        return None
+
+    return AnomalyResult(
+        provider=provider,
+        service=service,
+        account_id=account_id,
+        snapshot_date=snapshot_date,
+        severity=_severity(z_score, pct_change),
+        direction="spike" if pct_change > 0 else "drop",
+        pct_change=round(pct_change, 2),
+        z_score=round(z_score, 3),
+        baseline_mean=round(mean, 4),
+        current_amount=round(current_amount, 4),
+        metadata={"baseline": baseline_label},
+    )