Labsco
eelzinaty logo

Cloudability API

★ 3

from eelzinaty

A comprehensive Model Context Protocol (MCP) server for the Cloudability API, providing advanced cost management, Kubernetes container analytics, and budget forecasting capabilities.

🔥🔥🔥✓ VerifiedPaid serviceAdvanced setup
#email#automation#analytics#cloud#devops#git#maps#weather

Cloudability MCP Server

License: MIT Python 3.14+ FastMCP

A comprehensive Model Context Protocol (MCP) server for the Cloudability API, providing advanced cost management, Kubernetes container analytics, and budget forecasting capabilities.

🌟 Why Use This MCP Server?

  • 🔥 Container-First: Comprehensive Kubernetes cost allocation and monitoring
  • 📊 Advanced Analytics: 15 dimensions, 8 metrics, flexible filtering and grouping
  • 💰 Budget Management: Complete budget lifecycle with forecasting and alerts
  • 🚀 Production Ready: Full test coverage, type safety, and error handling
  • 🌍 Multi-Region: Support for US, EU, APAC, and ME Cloudability regions
  • 🔐 Flexible Auth: Bearer tokens, legacy Basic auth, or Frontdoor API keys for automatic token acquisition

Features

🚀 Comprehensive API Coverage

  • 🔥 Container Cost Allocation: Complete Kubernetes cost allocation and monitoring
  • 🔥 Container Provisioning: Cluster setup and Metrics Agent deployment
  • 🔥 Container Analytics: Usage patterns, resource allocation, and efficiency analysis
  • 🔥 Container Discovery: Labels and resource inventory via containers_report
  • Cost Reporting: Flexible, powerful cost analysis with 15 dimensions & 8 metrics
  • Asynchronous Reports: Queue long-running reports for background processing
  • Budgets & Forecasting: Complete budget lifecycle management and spending predictions
  • Budget Subscriptions: Email notifications for budget thresholds
  • Estimates: Current month spending projections with detailed breakdowns
  • Forecasts: Multi-month predictive analytics with confidence intervals
  • Vendor Accounts: List cloud provider credential accounts (AWS, Azure, GCP, IBM, OCI)

🔐 Flexible Authentication

  • Bearer Token: Modern apptio-opentoken authentication
  • Frontdoor API Keys: Automatic apptio-opentoken acquisition when keys are set in the environment
  • Basic Auth: Traditional API key authentication
  • Multi-Region Support: US, EU, APAC, and ME Cloudability API and Frontdoor login endpoints

📊 Advanced Analytics

  • Rich Filtering: Filter by cluster, namespace, workload type, and more
  • Flexible Grouping: Group results by multiple dimensions
  • Sorting & Pagination: Handle large datasets efficiently
  • Multiple Widget Types: Support for tables, KPIs, charts, and time series

🛠️ Developer Experience

  • FastMCP Framework: Modern MCP server implementation
  • Comprehensive Testing: Full test coverage with mocking
  • Type Safety: Complete type annotations for better IDE support
  • Clean Architecture: Separated business logic for maintainability

Testing

Run the test suite:

# Run unit tests (mocked HTTP; integration tests are skipped by default)
uv run pytest tests/ -v

# Run tests with coverage
uv run pytest tests/ -v --cov=main --cov-report=term-missing

# Run live MCP + Cloudability API integration tests (requires .env credentials)
cp .env.example .env   # set CLOUDABILITY_KEY_ACCESS, CLOUDABILITY_KEY_SECRET, CLOUDABILITY_ENVIRONMENT_ID
uv run pytest tests/test_mcp_integration.py -v -m integration

Integration tests cover 10 core read-only MCP tools (budgets, cost reporting, containers), 3 optional tools that skip when your tenant lacks access, plus a chained get_budget test.

Examples

Container Cost Allocation (Most Important!)

# Provision a new cluster for monitoring
cluster = provision_kubernetes_cluster(
    cluster_name="production-k8s",
    kubernetes_version="1.28",
    authorization="Bearer your-token"
)

# Get deployment YAML for Metrics Agent
deployment = get_cluster_deployment_yaml(
    cluster_id=cluster["result"]["id"],
    authorization="Bearer your-token"
)
# Save deployment["deployment_yaml"] and apply: kubectl apply -f deployment.yaml

# Analyze cost allocation by namespace (primary use case)
allocation = containers_report(
    start_date="2024-01-01",
    end_date="2024-01-31",
    group=["namespace"],
    metrics=["total_cost", "total_cost_efficiency"],
    authorization="Bearer your-token"
)

# Team-based cost allocation using labels
team_costs = containers_report(
    start_date="2024-01-01",
    end_date="2024-01-31",
    group=["cldy:labels:team", "namespace"],
    metrics=["total_cost", "total_cost_allocated"],
    filters=["cluster==your-cluster-uuid"],
    cost_type="total_adjusted_amortized",
    authorization="Bearer your-token"
)

# Workload-level cost breakdown for a namespace
service_costs = containers_report(
    start_date="2024-01-01",
    end_date="2024-01-31",
    group=["workload_name", "workload_type"],
    metrics=["total_cost"],
    filters=["namespace==production", "cluster==your-cluster-uuid"],
    authorization="Bearer your-token"
)

Container Resource Analysis

# Daily usage trends for capacity planning
usage_trends = get_container_resource_usage(
    start_date="2024-01-01",
    end_date="2024-01-31",
    metrics=["cpu/reserved", "memory/reserved_rss", "filesystem/usage"],
    filters=["cluster==your-cluster-uuid"],
    authorization="Bearer your-token"
)

# Discover available labels for cost allocation
labels = discover_container_labels(
    start_date="2024-01-01",
    end_date="2024-01-31",
    filters=["cluster==your-cluster-uuid"],
    authorization="Bearer your-token"
)

# Get detailed cluster information
cluster_info = get_detailed_cluster_info(
    start_date="2024-01-01",
    end_date="2024-01-31",
    authorization="Bearer your-token"
)

Basic Cost Analysis

# Get cost breakdown by namespace for the last month
result = containers_report(
    start_date="2024-01-01",
    end_date="2024-01-31",
    metrics=["total_cost", "total_cost_efficiency"],
    group=["namespace"],
    authorization="Bearer your-token"
)

Advanced Filtering

# Get cost data for specific cluster and production workloads
result = containers_report(
    start_date="2024-01-01",
    end_date="2024-01-31",
    filters=[
        "cluster==your-cluster-uuid",
        "namespace==production",
        "workload_type[]=deployment,statefulset"
    ],
    group=["workload_name"],
    sort=[{"sortMetric": "total_cost", "sortOrder": "desc"}],
    limit=10,
    authorization="Bearer your-token"
)

Budget Monitoring

# Check all budgets and their current status
budgets = list_budgets(authorization="Basic your-api-key:")

# Get detailed information for a specific budget
budget_details = get_budget(
    budget_id="budget-123",
    authorization="Basic your-api-key:"
)

Spending Estimates & Forecasts

# Get current month spending estimate (fields are under result)
estimate = get_spending_estimate(
    view_id="0",
    basis="cash",
    authorization="Bearer your-token"
)
summary = estimate["result"]
print(summary["estimatedSpend"], summary["currentDate"])

# Azure month-end estimate from service breakdown
azure_estimate = sum(
    row["estimatedSpend"]
    for row in summary["details"]
    if row["serviceName"].startswith("Azure")
)

# Generate 12-month forecast based on 6 months of history
forecast = get_spending_forecast(
    view_id="0",
    basis="cash",
    months_back=6,
    months_forward=12,
    use_current_estimate=True,
    remove_one_time_charges=True,
    authorization="Bearer your-token"
)
forecast_rows = forecast["result"]["forecast"]

Budget Management

# Create a quarterly budget
budget = create_new_budget(
    name="Q1 2024 Budget",
    basis="adjusted",
    view_id="0",
    months=[
        {"month": "2024-01", "threshold": 50000},
        {"month": "2024-02", "threshold": 55000},
        {"month": "2024-03", "threshold": 60000}
    ],
    authorization="Bearer your-token"
)

# Set up budget alerts
alert = create_budget_alert(
    budget_id=budget["result"]["id"],
    notify_exceeded=True,
    notify_expected=True,
    authorization="Bearer your-token"
)

# Update budget thresholds
updated_budget = modify_budget(
    budget_id=budget["result"]["id"],
    months=[
        {"month": "2024-01", "threshold": 45000},
        {"month": "2024-02", "threshold": 50000}
    ],
    authorization="Bearer your-token"
)

Advanced Cost Reporting

# Basic cost breakdown by vendor and region
basic_report = execute_cost_report(
    start_date="2024-01-01",
    end_date="2024-01-31",
    dimensions=["vendor", "region"],
    metrics=["total_amortized_cost", "usage_hours"],
    authorization="Bearer your-token"
)

# Advanced filtering and sorting
filtered_report = execute_cost_report(
    start_date="beginning of last month",
    end_date="end of last month",
    dimensions=["vendor", "service_name", "resource_identifier"],
    metrics=["total_amortized_cost", "total_cost_efficiency"],
    filters=[
        "transaction_type==usage",
        "total_amortized_cost>100",
        "region=@us-east"
    ],
    sort=["total_amortized_costDESC", "vendorASC"],
    limit=1000,
    authorization="Bearer your-token"
)

# Asynchronous reporting for large datasets
report_id = queue_cost_report(
    start_date="2024-01-01",
    end_date="2024-03-31",
    dimensions=["resource_identifier", "service_name", "region"],
    metrics=["total_amortized_cost", "usage_hours"],
    filters=["vendor==Amazon"],
    authorization="Bearer your-token"
)

# Check status and retrieve results
status = check_report_status(
    report_id=report_id["id"],
    authorization="Bearer your-token"
)

if status["status"] == "finished":
    results = get_queued_report_results(
        report_id=report_id["id"],
        authorization="Bearer your-token"
    )

# Discover available dimensions and metrics
measures = get_available_measures(authorization="Bearer your-token")
operators = get_filter_operators(authorization="Bearer your-token")

Development

Project Structure

cloudability-mcp-server/
├── main.py                      # Main MCP server with tool definitions
├── cloudability_tools.py        # Core API implementation
├── tests/
│   └── test_cloudability_tools.py # Comprehensive API tests
├── .env.example                 # Environment configuration template
├── pyproject.toml              # Project configuration
└── README.md                   # This documentation

Architecture

  • main.py: Clean MCP tool definitions using FastMCP decorators
  • cloudability_tools.py: Separated business logic with comprehensive API coverage
  • Flexible Authentication: Support for both Bearer tokens and Basic auth
  • Comprehensive Testing: Full test coverage with HTTP mocking
  • Type Safety: Complete type annotations for better development experience

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contribution Steps

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes with tests
  4. Run quality checks: uv run black . && uv run pytest
  5. Submit a pull request

Development Setup

# Clone your fork
git clone https://github.com/eelzinaty/cloudability-mcp-server.git
cd cloudability-mcp-server

# Install development dependencies
uv sync --group dev

# Run tests
uv run pytest tests/ -v

# Format code
uv run black . && uv run isort .

📚 Documentation

🐛 Issues & Support

📄 License

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

🙏 Acknowledgments

  • FastMCP: Modern MCP server framework
  • Model Context Protocol: The protocol specification
  • Cloudability: For providing comprehensive cloud cost management APIs

🔗 Related Projects

Made with ❤️ for the FinOps and Kubernetes communities