Cost Explorer MCP Server

Servidor MCP para analizar costes y uso de AWS a traves de la API de AWS Cost Explorer, disenado para despliegues en EKS con Pod Identity y asuncion de roles multi-cuenta.

Tabla de Contenidos

• Funcionalidades
• Arquitectura de Autenticacion
• Configuracion
• Validacion y Optimizacion de Costes
• Herramientas Disponibles
• Despliegue
• Tests
• Ejemplos de Uso
• Licencia

Funcionalidades

Analisis de costes y uso de AWS

• Desglose detallado de costes por servicio, region y otras dimensiones
• Consulta de datos historicos de costes para periodos de tiempo especificos
• Filtrado de costes por dimensiones, etiquetas y categorias de coste

Comparacion de costes entre periodos

• Uso de la funcionalidad de Cost Comparison de AWS Cost Explorer
• Comparacion de costes entre dos periodos para identificar cambios y tendencias
• Analisis de los principales factores de coste (top 10) para entender incrementos/decrementos

Prevision de costes futuros

• Generacion de previsiones basadas en patrones de uso historicos
• Predicciones con intervalos de confianza (80% o 95%)
• Granularidad de prevision diaria y mensual

Arquitectura multi-cuenta

• Soporte para multiples cuentas AWS con diferentes roles IAM
• Gestion de sesiones thread-safe con cache LRU (maximo 300 sesiones)
• Refresco automatico de tokens 5 minutos antes de su expiracion
• Deduplicacion de peticiones concurrentes (una sola llamada STS por cuenta)

Arquitectura de Autenticacion

Como funciona

Este servidor esta disenado para ejecutarse en EKS, donde el pod obtiene credenciales via EKS Pod Identity, y para cada peticion asume un rol IAM especifico (cross-account) basado en el client_id.

Flujo de autenticacion:

1. El pod obtiene credenciales base via EKS Pod Identity
2. La configuracion de clientes se carga desde AWS Secrets Manager (en produccion) o desde un fichero clients.json local (en desarrollo)
3. Para cada peticion de herramienta:

• Se envia el client_id
• El servidor busca el role_arn en la configuracion de clientes
• El servidor llama a sts:AssumeRole hacia el rol correspondiente
• Se crea un cliente de Cost Explorer (ce) y se cachea hasta la expiracion del token
• Los tokens se refrescan automaticamente antes de expirar

Carga de configuracion de clientes

El servidor prioriza las fuentes en este orden:

1. AWS Secrets Manager — si la variable CLIENTS_CONFIG_SECRET esta definida, carga la configuracion desde el secret indicado. La configuracion se cachea en memoria durante 5 minutos (configurable via CLIENTS_CONFIG_CACHE_TTL). Cuando se actualiza el secret, el servidor detecta el cambio automaticamente en el siguiente ciclo de cache sin necesidad de reinicio.

1. Fichero local — si CLIENTS_CONFIG_SECRET no esta definida, busca clients.json en la ruta indicada por CLIENTS_CONFIG_PATH o en ubicaciones por defecto relativas al modulo. El fichero se recarga automaticamente cuando cambia (deteccion por mtime).

Prerequisitos

• EKS con Pod Identity habilitado
• Rol base (pod role): el rol IAM asignado al pod via Pod Identity, con permisos para:
• sts:AssumeRole sobre cada ARN de rol de cuenta
• secretsmanager:GetSecretValue sobre el secret de configuracion
• Rol en cada cuenta target: permite la asuncion por el rol base

Gestion de concurrencia

El servidor maneja las peticiones concurrentes de forma segura:

• Caches thread-safe: Todas las caches usan locks para prevenir condiciones de carrera
• Deduplicacion de refresco: Si multiples peticiones necesitan refrescar el mismo token, solo se realiza una llamada STS
• Eviccion LRU: Maximo 300 sesiones cacheadas con eviccion automatica de las menos usadas

Permisos IAM necesarios

Rol base (identidad del pod via Pod Identity):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": [
        "arn:aws:iam::ACCOUNT_ID_1:role/mcp-cost-optimizer",
        "arn:aws:iam::ACCOUNT_ID_2:role/mcp-cost-optimizer"
      ]
    },
    {
      "Effect": "Allow",
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "arn:aws:iam::BASE_ACCOUNT_ID:secret:mcp-cost-optimizer/clients"
    }
  ]
}

Rol en cada cuenta target (mcp-cost-optimizer):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ce:GetCostAndUsage",
        "ce:GetCostForecast",
        "ce:GetDimensionValues",
        "ce:GetTags",
        "ce:GetCostAndUsageComparisons",
        "ce:GetCostComparisonDrivers",
        "ce:GetReservationUtilization",
        "ce:GetReservationCoverage",
        "ce:GetReservationPurchaseRecommendation",
        "ce:GetSavingsPlansCoverage",
        "ce:GetSavingsPlansUtilization",
        "ce:GetSavingsPlansPurchaseRecommendation",
        "cloudwatch:GetMetricStatistics",
        "cloudwatch:GetMetricData",
        "cloudwatch:ListMetrics",
        "ec2:DescribeRegions",
        "ec2:DescribeInstances",
        "ec2:DescribeVolumes",
        "ec2:DescribeSnapshots",
        "ec2:DescribeNatGateways",
        "ec2:DescribeAddresses",
        "elasticloadbalancing:DescribeLoadBalancers",
        "elasticloadbalancing:DescribeTargetGroups",
        "elasticloadbalancing:DescribeTargetHealth",
        "rds:DescribeDBInstances",
        "rds:DescribeDBRecommendations",
        "s3:ListAllMyBuckets",
        "s3:GetBucketLocation",
        "s3:GetLifecycleConfiguration",
        "s3:GetBucketVersioning"
      ],
      "Resource": "*"
    }
  ]
}

Trust policy en cada rol de cuenta target:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::BASE_ACCOUNT_ID:role/mcp-cost-optimizer-CLUSTER_ID"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Configuracion

Configuracion multi-cuenta (clients.json)

El servidor utiliza el client_id para buscar el rol a asumir. La configuracion puede estar en AWS Secrets Manager o en un fichero local.

#### Ejemplo de configuracion

{
  "clients": {
    "cuenta-produccion": {
      "role_arn": "arn:aws:iam::ACCOUNT_ID_1:role/mcp-cost-optimizer",
      "account_id": "ACCOUNT_ID_1",
      "account_type": "payer",
      "description": "Cuenta de gestion (payer)"
    },
    "cuenta-desarrollo": {
      "role_arn": "arn:aws:iam::ACCOUNT_ID_2:role/mcp-cost-optimizer",
      "account_id": "ACCOUNT_ID_2",
      "account_type": "linked",
      "payer_id": "cuenta-produccion",
      "description": "Cuenta de desarrollo (linked)"
    }
  }
}

Actualizar la configuracion en produccion

aws secretsmanager put-secret-value \
  --secret-id "mcp-cost-optimizer/clients" \
  --secret-string file://clients.json \
  --region eu-west-1 --profile <profile>

El servidor detecta el cambio automaticamente en los proximos 5 minutos sin reinicio.

Variables de Entorno

*Se requiere uno de los dos: CLIENTS_CONFIG_SECRET (produccion) o CLIENTS_CONFIG_PATH / fichero local (desarrollo).

Herramientas Disponibles

El servidor MCP de Cost Explorer proporciona las siguientes herramientas:

Utilidades

Consultas de Costes

Analisis y Comparacion

Inventario

Utilizacion

Uso Multi-Cuenta

Importante: Siempre hay que pasar el client_id al invocar una herramienta. El servidor asumira el rol correspondiente de la configuracion de clientes.

#### Ejemplo: get_cost_and_usage

{
  "client_id": "cuenta-produccion",
  "date_range": {
    "start_date": "2026-01-01",
    "end_date": "2026-01-31"
  },
  "granularity": "MONTHLY",
  "group_by": "SERVICE",
  "metric": "UnblendedCost"
}

Validacion y Optimizacion de Costes

Como funciona la validacion

Cada llamada a la API de Cost Explorer cuesta $0.01. El servidor realiza validaciones en las peticiones antes de enviarlas a AWS.

Validaciones locales (siempre se ejecutan, sin llamadas a AWS):

• Formato de fecha (YYYY-MM-DD)
• Logica de rango de fechas (inicio antes que fin)
• Restricciones por granularidad (ej. HOURLY maximo 14 dias)
• Validacion de claves de dimension (SERVICE, REGION, etc.)
• Validacion de estructura de filtros (operadores And, Or, Not)
• Validacion de agrupacion (group by)

Validaciones AWS (opcionales, deshabilitadas por defecto):

• Validar que los valores de dimension existen (ej. "Amazon EC2" es un valor valido de SERVICE)
• Validar que los valores de etiqueta existen

Estimacion de costes

Despliegue

Modos de Transporte

Desarrollo local

# Instalar dependencias
uv sync

# Ejecutar con fichero local
CLIENTS_CONFIG_PATH=./clients.json uv run cost-optimizer

Build y push a ECR

aws ecr get-login-password --region eu-west-1 --profile <profile> \
  | docker login --username AWS --password-stdin \
    675492141136.dkr.ecr.eu-west-1.amazonaws.com

docker build -t mcp-costoptimizer-aws .
docker tag mcp-costoptimizer-aws:latest \
  675492141136.dkr.ecr.eu-west-1.amazonaws.com/mcp-costoptimizer-aws:latest
docker push \
  675492141136.dkr.ecr.eu-west-1.amazonaws.com/mcp-costoptimizer-aws:latest

Despliegue en EKS (via Terraform/Terragrunt)

El despliegue en EKS se gestiona desde el repo innovation-account. Requiere:

1. Crear el secret en Secrets Manager (una vez):

aws secretsmanager create-secret \
  --name "mcp-cost-optimizer/clients" \
  --secret-string file://clients.json \
  --region eu-west-1 --profile <profile>

1. Crear manualmente el rol mcp-cost-optimizer en cada cuenta target con los permisos y trust policy indicados en Permisos IAM necesarios.

1. Aplicar la infra:

cd config/eu-west-1/envs/cost-optimizer
terragrunt run-all apply

El MCP quedara disponible internamente en el cluster en:

http://mcp.cost-optimizer.svc.cluster.local:8000

Tests

Ejecutar tests unitarios

uv sync --dev
source .venv/bin/activate
pytest tests/ -v -o "addopts="

Ejemplos de Uso

Analisis de costes

Muestrame los costes de AWS de los ultimos 3 meses agrupados por servicio
Desglosa los costes de S3 por clase de almacenamiento del primer trimestre de 2026
Cuales fueron mis costes de instancias reservadas vs bajo demanda en mayo?

Comparacion de costes

Compara mis costes de AWS entre abril y mayo de 2026
Por que aumento mi factura de AWS en junio comparado con mayo?
Que causo el pico en mis costes de S3 el mes pasado?

Previsiones

Haz una prevision de mis costes de AWS para el proximo mes
Cual sera mi factura total de AWS para el resto de 2026?

Licencia

Este proyecto esta licenciado bajo la Licencia Apache 2.0 - consulta el fichero LICENSE para mas detalles.