Cloudability Api Server

Cloudability MCP Server

一款功能全面的 Cloudability API 模型上下文协议（MCP）服务，提供高级成本管理、Kubernetes 容器分析和预算预测功能。

🌟 为什么使用此 MCP 服务？

• 🔥 容器优先：全面的 Kubernetes 成本分配与监控
• 📊 高级分析：15 个维度、8 个指标，支持灵活筛选和分组
• 💰 预算管理：完整的预算生命周期管理，支持预测和警报
• 🚀 可用于生产环境：完整的测试覆盖、类型安全和错误处理
• 🌍 多区域支持：支持美国、欧盟、亚太和中东 Cloudability 区域
• 🔐 灵活的身份验证：支持 Bearer token、旧版 Basic 身份验证，或通过 Frontdoor API 密钥自动获取 token

🚀 快速开始

前提条件

• Python 3.14+（现代类型注解所必需）
• uv（推荐的包管理器）
• Cloudability API 访问权限（.env 文件中的 Bearer token、API 密钥或 Frontdoor API 密钥）

安装

# 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 客户端配置

添加到 MCP 客户端配置中：

{
  "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"
      }
    }
  }
}

功能

🚀 全面的 API 覆盖

• 🔥 容器成本分配：完整的 Kubernetes 成本分配与监控
• 🔥 容器配置：集群设置和 Metrics Agent 部署
• 🔥 容器分析：使用模式、资源分配和效率分析
• 🔥 容器发现：通过 containers_report 获取标签和资源清单
• 成本报告：使用 15 个维度和 8 个指标进行灵活、强大的成本分析
• 异步报告：将长时间运行的报告加入队列，在后台处理
• 预算与预测：完整的预算生命周期管理和支出预测
• 预算订阅：预算阈值的电子邮件通知
• 估算：当月支出预测，附带详细分类
• 预测：多月预测分析，带置信区间
• 供应商账户：列出云服务提供商的凭据账户（AWS、Azure、GCP、IBM、OCI）

🔐 灵活的身份验证

• Bearer Token：现代 apptio-opentoken 身份验证
• Frontdoor API 密钥：在环境中设置密钥后自动获取 apptio-opentoken
• Basic Auth：传统 API 密钥身份验证
• 多区域支持：美国、欧盟、亚太和中东 Cloudability API 与 Frontdoor 登录端点

📊 高级分析

• 丰富的筛选：按集群、命名空间、工作负载类型等筛选
• 灵活分组：按多个维度对结果分组
• 排序与分页：高效处理大型数据集
• 多种 Widget 类型：支持表格、KPI、图表和时间序列

🛠️ 开发者体验

• FastMCP 框架：现代 MCP 服务实现
• 全面测试：通过模拟实现完整的测试覆盖
• 类型安全：完整的类型注解，提供更好的 IDE 支持
• 清晰的架构：分离业务逻辑，便于维护

安装

此项目使用 uv 进行依赖管理。请确保已安装 uv。

# Install dependencies
uv sync

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

配置

根据 .env.example 创建 .env 文件：

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

环境变量

将 .env.example 复制为 .env，并配置以下变量。

变量	必填	说明
CLOUDABILITY_API_URL	否（默认为 US）	所在区域的 Cloudability API 基础 URL
CLOUDABILITY_ENVIRONMENT_ID	是（Bearer 身份验证需要）	从 Access Administration 获取的环境 ID
CLOUDABILITY_KEY_ACCESS	否	用于自动获取令牌的 Frontdoor 公共 API 密钥
CLOUDABILITY_KEY_SECRET	否	Frontdoor 私有 API 密钥（与 CLOUDABILITY_KEY_ACCESS 配套使用）
CLOUDABILITY_FRONTDOOR_URL	否（默认为 US）	所在区域的 Frontdoor API 密钥登录端点
CLOUDABILITY_DEFAULT_VIEW_ID	是（容器工具需要）	用于容器报告和集群调用的默认视图 ID

# 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

区域端点

Cloudability API（CLOUDABILITY_API_URL）

区域	URL
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

Frontdoor 登录（CLOUDABILITY_FRONTDOOR_URL）

区域	URL
US	https://frontdoor.apptio.com/service/apikeylogin
EU	https://frontdoor-eu.apptio.com/service/apikeylogin
AU	https://frontdoor-au.apptio.com/service/apikeylogin

身份验证方法

1. Frontdoor API 密钥（可选，服务端）

设置 CLOUDABILITY_KEY_ACCESS 和 CLOUDABILITY_KEY_SECRET 后，服务端会通过 CLOUDABILITY_FRONTDOOR_URL 将其交换为 apptio-opentoken。工具调用可以省略 authorization 参数。还需设置 CLOUDABILITY_ENVIRONMENT_ID——Bearer 身份验证仍然需要该变量。

2. Bearer 令牌

适用于使用 apptio-opentoken 的新式 Cloudability 环境：

• 在环境中设置 CLOUDABILITY_ENVIRONMENT_ID
• 在工具调用中传入 authorization: "Bearer your-apptio-opentoken"（除非由 Frontdoor 密钥代为处理身份验证）

3. Basic 身份验证（旧版）

适用于传统 API 密钥身份验证：

• 在工具调用中传入 authorization: "Basic your-api-key:"
• 无需环境 ID

用法

运行服务

uv run python main.py

MCP 参考资源

用于构建成本报告的只读参考数据（已缓存，默认 TTL 为 15 分钟，由 CLOUDABILITY_RESOURCE_CACHE_TTL_SECONDS 控制）：

URI	说明
cloudability://config	服务配置（API URL、默认视图 ID、身份验证模式——不包含密钥）
cloudability://measures	成本报告维度和指标目录
cloudability://measures/allocated	支持成本分配的度量
cloudability://filter-operators	筛选运算符参考（==、=@、[]=、…）
cloudability://saved-reports	已保存的成本报告定义

在 MCP 客户端中使用 resources/read，或调用对应工具（get_available_measures 等）获取相同数据。

可用工具

🔥 容器成本分配工具

provision_kubernetes_cluster

为 Cloudability 监控设置新集群，并自动部署 Metrics Agent。

get_cluster_deployment_yaml

获取部署配置，用于在集群中安装 Cloudability Metrics Agent。

containers_report

主要容器成本分摊工具——通过 POST /v3/containers/report 取代已停用的 /containers/allocations 和 /containers/counts API。

主要功能：

• 共享资源分摊：按命名空间、工作负载、集群和标签提供公平分摊及分摊成本指标
• 灵活分组：命名空间、工作负载类型、工作负载名称、Pod、标签等
• 筛选：集群 UUID、命名空间、工作负载类型等

参数：

• group：分组维度（例如，["namespace"]、["cldy:labels:team"]）
• metrics：报告指标（例如，["total_cost"]、["total_cost_efficiency"]）
• filters：分析范围（例如，["cluster==uuid"]、["namespace==production"]）
• cost_type："adjusted" 或 "total_adjusted_amortized"

返回：

• result.data 中包含带分组维度和指标的行
• 通过 result.pagination.nextToken 分页

get_container_resource_usage

每日用量趋势，用于容量规划和资源规格优化分析。

discover_container_labels

查找可用的 Kubernetes 标签，用于自定义成本分摊分组。

get_detailed_cluster_info

全面的集群元数据，包含节点详情和数据收集状态。

🚀 主要工具

list_clusters

获取所有 Kubernetes 集群及其 UUID 和元数据。

list_budgets

获取所有预算配置及其当前状态和阈值。

get_budget

获取详细的预算信息，包括支出跟踪和提醒。

list_aws_accounts

获取 Cloudability 中配置的 AWS 供应商凭证账户（GET /v3/vendors/AWS/accounts?viewId=0）。

list_azure_accounts

获取 Cloudability 中配置的 Azure 供应商凭证账户（GET /v3/vendors/azure/accounts?viewId=0）。

list_gcp_accounts

获取 Cloudability 中配置的 GCP 供应商凭证账户（GET /v3/vendors/gcp/accounts?viewId=0）。

list_ibm_accounts

获取 Cloudability 中配置的 IBM Cloud 供应商凭证账户（GET /v3/vendors/ibm/accounts?viewId=0）。

list_oci_accounts

获取 Cloudability 中配置的 OCI 供应商凭证账户（GET /v3/vendors/oci/accounts?viewId=0）。

📊 预算与预测工具

get_spending_estimate

当前月份支出预测，包含详细的服务明细和每日进度。

主要功能：

• 根据本月至今的用量实时估算支出
• 服务级支出驱动因素（AWS EC2、RDS 等）
• 每日累计支出进度
• 与上月实际支出对比
• 速率限制：每位用户每分钟 10 次请求，每个组织每分钟 20 次请求

**响应格式：**标准 Cloudability v3 信封。所有字段均位于 result 下（而非顶层）：

{
  "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"
      }
    ]
  }
}

对于供应商或服务明细，请使用 result["details"]（例如，筛选 serviceName 以 Azure 开头的行）。使用服务器配置的默认视图时，省略 view_id，或将其设为 cloudability://config 资源中的 default_view_id（0 表示所有组织成本数据）。

get_spending_forecast

多月预测分析，包含置信区间和历史对比。

参数：

• months_back（3-24）：用于建模的历史数据
• months_forward（1-24）：预测时间范围
• use_current_estimate：在模型中包含当前月份
• remove_credits：从分析中排除抵扣项
• remove_one_time_charges：筛除一次性费用

**返回：**Cloudability v3 信封，预测数据位于 result 下（例如 result.forecast、result.forecastDetail、result.actual、result.parameters）。

create_new_budget

创建预算，并设置每月阈值和成本依据配置。

modify_budget

更新现有预算，包括修改阈值或配置。

remove_budget

从系统中永久删除预算。

create_budget_alert

设置电子邮件通知，用于预算阈值超限提醒。

通知类型：

• notify_exceeded：实际支出超出预算时提醒
• notify_expected：预计支出超出预算时提醒

list_budget_alerts

列出预算订阅及通知偏好设置。

modify_budget_alert / remove_budget_alert

更新或删除预算通知订阅。

📊 成本报告工具

execute_cost_report

主要成本报告工具，提供高级分析和灵活配置。

主要功能：

• 最多 15 个维度：vendor、region、service_name、resource_identifier 等。
• 最多 8 个指标：total_cost、amortized_cost、usage_hours 等。
• 高级筛选：支持 12 种运算符（==、!=、>、<、=@、[]= 等）
• 灵活排序：支持多列排序，可用 ASC/DESC
• 自动分页：处理 10,000 行以上的数据集
• 相对日期：“上月初”、“本季度末”
• 图表格式：支持按日期可视化
• 视图集成：应用已保存的视图和分配

参数：

• dimensions：分组维度列表（最多 15 个）
• metrics：成本/用量指标列表（最多 8 个）
• filters：筛选表达式（例如，["transaction_type==usage"]）
• sort：排序表达式（例如，["total_costDESC"]）
• start_date/end_date：日期范围或相对日期
• view_id：应用已保存的视图（0 表示不受限制）
• apply_allocations：包含分配后的成本

queue_cost_report

针对运行时间较长或复杂的报告进行异步报告处理。

优势：

• 后台处理：不受超时限制
• 大型数据集：分页上限为 30,000 行，而非 10,000 行
• 状态跟踪：使用 check_report_status 监控进度
• 速率限制：每位用户最多 20 个请求

list_saved_cost_reports

查找可用报告，查看完整配置和共享信息。

get_available_measures

查看维度和指标及其详细元数据和分组信息。

get_filter_operators

所有支持的筛选比较运算符的参考指南。

check_report_status / get_queued_report_results

管理异步报告，从排队到完成。

测试

运行测试套件：

# 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

集成测试涵盖 10 个核心只读 MCP 工具（预算、成本报告、容器）、3 个在租户无访问权限时会跳过的可选工具，以及一个链式 get_budget 测试。

示例

容器成本分配（最重要！）

# 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"
)

容器资源分析

# 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"
)

基本成本分析

# 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"
)

高级筛选

# 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"
)

预算监控

# 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:"
)

支出估算与预测

# 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"]

预算管理

# 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"
)

高级成本报告

# 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")

开发

项目结构

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

架构

• main.py：使用 FastMCP 装饰器定义简洁的 MCP 工具
• cloudability_tools.py：分离业务逻辑，全面覆盖 API
• 灵活的身份验证：支持 Bearer 令牌和 Basic 身份验证
• 全面测试：通过 HTTP 模拟实现完整测试覆盖
• 类型安全：完整的类型注解，带来更好的开发体验

🤝 贡献

欢迎贡献！详情请参阅贡献指南。

快速贡献步骤

1. Fork 仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 编写更改并添加测试
4. 运行质量检查：uv run black . && uv run pytest
5. 提交拉取请求

开发环境设置

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

📚 文档

• 开发指南：全面的开发文档
• 贡献指南：如何为项目做出贡献
• API 文档：完整的工具架构定义
• Cloudability API 文档：官方 API 文档

🐛 问题与支持

• 错误报告：GitHub Issues
• 功能请求：GitHub Issues
• 讨论：GitHub Discussions

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🙏 致谢

• FastMCP：现代 MCP 服务框架
• Model Context Protocol：协议规范
• Cloudability：提供全面的云成本管理 API

🔗 相关项目

• MCP 服务：官方 MCP 服务实现
• Claude Desktop：热门 MCP 客户端
• 其他 MCP 工具：社区 MCP 实现

---

献给 FinOps 和 Kubernetes 社区 ❤️