Cloudability MCP Server

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

🚀 Quick Start

Prerequisites

• Python 3.14+ (required for modern type annotations)
• uv (recommended package manager)
• Cloudability API access (Bearer token, API key, or Frontdoor API keys in `.env`)

Installation

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

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

# Set up configuration
cp .env.example .env
# Edit .env with your Cloudability credentials

# Run the server
uv run python main.py

MCP Client Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "cloudability": {
      "command": "uv",
      "args": ["run", "python", "main.py"],
      "cwd": "/path/to/cloudability-mcp-server",
      "env": {
        "CLOUDABILITY_API_URL": "https://api.cloudability.com/v3",
        "CLOUDABILITY_ENVIRONMENT_ID": "your-environment-id",
        "CLOUDABILITY_DEFAULT_VIEW_ID": "12345",
        "CLOUDABILITY_KEY_ACCESS": "your-public-key",
        "CLOUDABILITY_KEY_SECRET": "your-private-key",
        "CLOUDABILITY_FRONTDOOR_URL": "https://frontdoor.apptio.com/service/apikeylogin"
      }
    }
  }
}

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

Installation

This project uses `uv` for dependency management. Make sure you have `uv` installed.

# Install dependencies
uv sync

# Install development dependencies (for testing)
uv sync --dev

Configuration

Create a `.env` file based on `.env.example`:

# Copy the example configuration
cp .env.example .env

Environment Variables

Copy `.env.example` to `.env` and configure the variables below.

# Cloudability API Base URL (choose based on your region)
# US: https://api.cloudability.com/v3
# EU: https://api-eu.cloudability.com/v3
# APAC: https://api-au.cloudability.com/v3
# ME: https://api-me.cloudability.com/v3
CLOUDABILITY_API_URL=https://api.cloudability.com/v3

# Required for Bearer token authentication (apptio-opentoken)
# Get this from your Access Administration environment
CLOUDABILITY_ENVIRONMENT_ID=your-environment-id-here

# Optional: Frontdoor API keys for automatic apptio-opentoken acquisition
# When set, tools can omit the authorization parameter
# CLOUDABILITY_KEY_ACCESS=your-public-key-here
# CLOUDABILITY_KEY_SECRET=your-private-key-here

# Optional: Frontdoor login URL (defaults to US region)
# US: https://frontdoor.apptio.com/service/apikeylogin
# EU: https://frontdoor-eu.apptio.com/service/apikeylogin
# AU: https://frontdoor-au.apptio.com/service/apikeylogin
# CLOUDABILITY_FRONTDOOR_URL=https://frontdoor.apptio.com/service/apikeylogin

# Default view ID for containers API calls (required for containers/report and clusters)
CLOUDABILITY_DEFAULT_VIEW_ID=12345

Regional endpoints

Cloudability API (`CLOUDABILITY_API_URL`)

Frontdoor login (`CLOUDABILITY_FRONTDOOR_URL`)

Authentication Methods

1. Frontdoor API Keys (optional, server-side)

When `CLOUDABILITY_KEY_ACCESS` and `CLOUDABILITY_KEY_SECRET` are set, the server exchanges them for an apptio-opentoken via `CLOUDABILITY_FRONTDOOR_URL`. Tool calls can omit the `authorization` parameter. Set `CLOUDABILITY_ENVIRONMENT_ID` as well — Bearer authentication still requires it.

2. Bearer Token

For modern Cloudability environments using apptio-opentoken:

• Set `CLOUDABILITY_ENVIRONMENT_ID` in your environment
• Pass `authorization: "Bearer your-apptio-opentoken"` to tool calls (unless Frontdoor keys handle auth for you)

3. Basic Auth (Legacy)

For traditional API key authentication:

• Pass `authorization: "Basic your-api-key:"` to tool calls
• No environment ID required

Usage

Running the Server

uv run python main.py

MCP Reference Resources

Read-only reference data for building cost reports (cached, default TTL 15 minutes via `CLOUDABILITY_RESOURCE_CACHE_TTL_SECONDS`):

Use `resources/read` in your MCP client, or call the matching tools (`get_available_measures`, etc.) for the same data.

Available Tools

🔥 Container Cost Allocation Tools

`provision_kubernetes_cluster`

Set up new clusters for Cloudability monitoring with automated Metrics Agent deployment.

`get_cluster_deployment_yaml`

Get deployment configuration for installing the Cloudability Metrics Agent in your cluster.

`containers_report`

Primary container cost allocation tool — replaces the retired `/containers/allocations` and `/containers/counts` APIs with `POST /v3/containers/report`.

Key Features:

• Shared resource allocation: Fairshare and allocated cost metrics by namespace, workload, cluster, and labels
• Flexible grouping: namespace, workload_type, workload_name, pod, labels, etc.
• Filtering: cluster UUID, namespace, workload type, and more

Parameters:

• `group`: Grouping dimensions (e.g., ["namespace"], ["cldy:labels:team"])
• `metrics`: Report metrics (e.g., ["total_cost", "total_cost_efficiency"])
• `filters`: Scope analysis (e.g., ["cluster==uuid", "namespace==production"])
• `cost_type`: "adjusted" or "total_adjusted_amortized"

Returns:

• `result.data` rows with grouped dimensions and metrics
• Pagination via `result.pagination.nextToken`

`get_container_resource_usage`

Daily usage trends for capacity planning and rightsizing analysis.

`discover_container_labels`

Find available Kubernetes labels for custom cost allocation groupings.

`get_detailed_cluster_info`

Comprehensive cluster metadata with node details and data collection status.

🚀 Primary Tools

`list_clusters`

Get all Kubernetes clusters with their UUIDs and metadata.

`list_budgets`

Get all budget configurations with current status and thresholds.

`get_budget`

Get detailed budget information including spend tracking and alerts.

`list_aws_accounts`

Get AWS vendor credential accounts configured in Cloudability (`GET /v3/vendors/AWS/accounts?viewId=0`).

`list_azure_accounts`

Get Azure vendor credential accounts configured in Cloudability (`GET /v3/vendors/azure/accounts?viewId=0`).

`list_gcp_accounts`

Get GCP vendor credential accounts configured in Cloudability (`GET /v3/vendors/gcp/accounts?viewId=0`).

`list_ibm_accounts`

Get IBM Cloud vendor credential accounts configured in Cloudability (`GET /v3/vendors/ibm/accounts?viewId=0`).

`list_oci_accounts`

Get OCI vendor credential accounts configured in Cloudability (`GET /v3/vendors/oci/accounts?viewId=0`).

📊 Budgets & Forecasting Tools

`get_spending_estimate`

Current month spending projections with detailed service breakdowns and daily progression.

Key Features:

• Real-time spending estimates based on month-to-date usage
• Service-level spending drivers (AWS EC2, RDS, etc.)
• Daily cumulative spending progression
• Comparison with previous month actuals
• Rate limiting: 10 requests/user/minute, 20/org/minute

Response format: Standard Cloudability v3 envelope. All fields are under `result` (not top-level):

{
  "result": {
    "estimatedSpend": 35615446.36,
    "previousMonthSpend": 33819722.57,
    "previousMonthFinalized": true,
    "currentDate": "2026-05-24",
    "cumulativeMtdSpend": [{"date": "2026-05-01", "spend": 1615288.82}],
    "details": [
      {
        "serviceName": "Azure Compute",
        "estimatedSpend": 5568954.48,
        "mtdSpend": 4128094.29,
        "previousMonthSpend": 5409219.11,
        "usageFamily": "Instance Usage"
      }
    ]
  }
}

Use `result["details"]` for vendor or service breakdowns (for example, filter lines where `serviceName` starts with `Azure`). Omit `view_id` or set it from the `cloudability://config` resource `default_view_id` when using the server's configured default view (`0` means all org cost data).

`get_spending_forecast`

Multi-month predictive analytics with confidence intervals and historical comparison.

Parameters:

• `months_back` (3-24): Historical data for modeling
• `months_forward` (1-24): Forecast horizon
• `use_current_estimate`: Include current month in model
• `remove_credits`: Exclude credits from analysis
• `remove_one_time_charges`: Filter out one-time costs

Returns: Cloudability v3 envelope with forecast data under `result` (for example `result.forecast`, `result.forecastDetail`, `result.actual`, `result.parameters`).

`create_new_budget`

Create budgets with monthly thresholds and cost basis configuration.

`modify_budget`

Update existing budgets with new thresholds or configuration changes.

`remove_budget`

Delete budgets permanently from the system.

`create_budget_alert`

Set up email notifications for budget threshold breaches.

Notification Types:

• `notify_exceeded`: Alerts when actual spend exceeds budget
• `notify_expected`: Alerts when projected spend exceeds budget

`list_budget_alerts`

List budget subscriptions and notification preferences.

`modify_budget_alert` / `remove_budget_alert`

Update or delete budget notification subscriptions.

📊 Cost Reporting Tools

`execute_cost_report`

Primary cost reporting tool with advanced analytics and flexible configuration.

Key Features:

• Up to 15 dimensions: vendor, region, service_name, resource_identifier, etc.
• Up to 8 metrics: total_cost, amortized_cost, usage_hours, etc.
• Advanced filtering: 12 operators (==, !=, >, 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](CONTRIBUTING.md) 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

- **[Development Guide](DEVELOPMENT.md)**: Comprehensive development documentation
- **[Contributing Guide](CONTRIBUTING.md)**: How to contribute to the project
- **[API Documentation](tool.yaml)**: Complete tool schema definitions
- **[Cloudability API Docs](https://developers.cloudability.com/)**: Official API documentation

## 🐛 Issues & Support

- **Bug Reports**: [GitHub Issues](https://github.com/eelzinaty/cloudability-mcp-server/issues)
- **Feature Requests**: [GitHub Issues](https://github.com/eelzinaty/cloudability-mcp-server/issues)
- **Discussions**: [GitHub Discussions](https://github.com/eelzinaty/cloudability-mcp-server/discussions)

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- **[FastMCP](https://github.com/jlowin/fastmcp)**: Modern MCP server framework
- **[Model Context Protocol](https://modelcontextprotocol.io/)**: The protocol specification
- **Cloudability**: For providing comprehensive cloud cost management APIs

## 🔗 Related Projects

- **[MCP Servers](https://github.com/modelcontextprotocol/servers)**: Official MCP server implementations
- **[Claude Desktop](https://claude.ai/desktop)**: Popular MCP client
- **[Other MCP Tools](https://github.com/topics/model-context-protocol)**: Community MCP implementations

---

**Made with ❤️ for the FinOps and Kubernetes communities**