awslabs.billing-cost-management-mcp-server 0.0.19

A Model Context Protocol (MCP) server that provides tools for AWS Billing and Cost Management by wrapping boto3 SDK functions.

AWS Billing and Cost Management MCP Server

MCP server for accessing AWS Billing and Cost Management capabilities.

Important Note: This server accesses cost and usage data from AWS Billing and Cost Management APIs. All API calls are performed using the caller's AWS credentials and follow AWS service limits and quotas.

Features

AWS Free Tier

• Free Tier optimization: Monitor Free Tier usage and avoid unexpected charges

AWS Cost and Usage Analysis

• Cost Explorer insights: Analyze historical and forecasted AWS costs with flexible grouping and filtering
• Usage metrics analysis: Track resource usage trends across your AWS environment
• Budget monitoring: Check existing budgets and their status against actual spending
• Cost anomaly detection: Identify unusual spending patterns and their root causes

Cost Optimization Recommendations

• Compute Optimizer recommendations: Get right-sizing suggestions for EC2, Lambda, EBS, and more
• Cost Optimization Hub: Access cost-saving opportunities across your AWS environment

Savings Plans and Reserved Instanaces

• Reserved Instance planning: Analyze RI coverage and receive purchase recommendations
• Savings Plans guidance: Get personalized Savings Plans recommendations based on usage patterns

S3 Storage Lens Analysis

• Storage metrics querying: Run SQL queries against Storage Lens metrics data
• Storage cost breakdown: Analyze S3 storage costs by bucket, storage class, and region
• Storage optimization opportunities: Identify lifecycle policy opportunities and cost-saving measures

Cost and Usage Comparison

• Month-over-month comparisons: Compare cost and usage between time periods with detailed breakdown
• Multi-account analysis: Analyze costs across multiple linked accounts
• Cost driver identification: Identify key factors driving cost changes

AWS Billing and Cost Management Pricing Calculator

• Workload estimate insights: Query workload estimates to see what usage you have estimated

AWS Billing Conductor & Proforma Cost Analysis

• Billing group management: List and filter billing groups with details on type, status, pricing plans, and member accounts
• Account associations: View linked account associations with billing groups, filter by monitored/unmonitored status
• Billing group cost reports: Retrieve cost report summaries comparing actual AWS charges vs proforma costs with margin analysis
• Detailed cost breakdowns: Get billing group cost reports broken down by service name or billing period
• Pricing rules and plans: List pricing rules (MARKUP, DISCOUNT, TIERING) and pricing plans with their associations
• Custom line items: List custom cost allocations including support fees, shared service costs, taxes, credits, and RI/SP distribution

Cost Allocation Tags

• Tag activation status: List cost allocation tags with filters by status (Active/Inactive), type (AWSGenerated/UserDefined), and specific tag keys
• Backfill history: Retrieve the history of tag backfill requests that retroactively apply activation status to historical billing data

Cost Category Definitions

• Describe cost categories: Get the full definition of a cost category including rules, split charge rules, and processing status
• List cost categories: List all cost category definitions in the account with summary metadata and filtering by effective date or supported resource types

Specialized Cost Optimization Prompts

• Graviton migration analysis: Guided analysis to identify EC2 instances suitable for AWS Graviton migration
• Savings Plans analysis: Structured recommendations for optimal Savings Plans purchases based on usage patterns

Prerequisites

1. Install uv from Astral or the GitHub README
2. Install Python 3.10 or newer using uv python install 3.10 (or a more recent version)
3. Set up AWS credentials with access to AWS services
   • You need an AWS account with appropriate permissions
   • Configure AWS credentials with aws configure or environment variables
   • Ensure your IAM role/user has permissions to access AWS Billing and Cost Management APIs

Installation

Kiro	Cursor	VS Code

⚡ Using uv

Configure the MCP server in your MCP client configuration (e.g., for Kiro, edit ~/.kiro/settings/mcp.json):

For Linux/MacOS users:

{
  "mcpServers": {
    "awslabs.billing-cost-management-mcp-server": {
      "command": "uvx",
      "args": [
         "awslabs.billing-cost-management-mcp-server@latest"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR",
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

For Windows users:

{
  "mcpServers": {
    "awslabs.billing-cost-management-mcp-server": {
      "command": "uvx",
      "args": [
         "--from",
         "awslabs.billing-cost-management-mcp-server@latest",
         "awslabs.billing-cost-management-mcp-server.exe"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR",
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Using Docker

Or docker after a successful docker build -t awslabs/billing-cost-management-mcp-server .:

# fictitious `.env` file with AWS temporary credentials
AWS_ACCESS_KEY_ID=ASIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_SESSION_TOKEN=AQoEXAMPLEH4aoAH0gNCAPy...truncated...zrkuWJOgQs8IZZaIv2BXIa2R4Olgk
AWS_REGION=us-east-1

{
  "mcpServers": {
    "awslabs.billing-cost-management-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "--interactive",
        "--env",
        "FASTMCP_LOG_LEVEL=ERROR",
        "--env-file",
        "/full/path/to/file/above/.env",
        "awslabs/billing-cost-management-mcp-server:latest"
      ],
      "env": {},
      "disabled": false,
      "autoApprove": []
    }
  }
}

NOTE: Your credentials will need to be kept refreshed from your host

Storage Lens Configuration

To use the Storage Lens functionality, you'll need to set the following environment variables:

• STORAGE_LENS_MANIFEST_LOCATION: S3 URI to your Storage Lens manifest file or folder (e.g., s3://bucket-name/storage-lens/manifests/)
• STORAGE_LENS_OUTPUT_LOCATION (optional): S3 location for Athena query results (defaults to the same bucket as the manifest with an athena-results/ suffix)

Example configuration:

"env": {
  "AWS_PROFILE": "your-aws-profile",
  "AWS_REGION": "us-east-1",
  "STORAGE_LENS_MANIFEST_LOCATION": "s3://your-bucket/storage-lens-data/",
  "STORAGE_LENS_OUTPUT_LOCATION": "s3://your-bucket/athena-results/"
}

AWS Authentication

The MCP server requires specific AWS permissions and configuration:

Required Permissions

Your AWS IAM role or user needs permissions to access various AWS Billing and Cost Management APIs:

Cost Explorer:

• ce:GetReservationPurchaseRecommendation
• ce:GetReservationCoverage
• ce:GetReservationUtilization
• ce:GetSavingsPlansUtilization
• ce:GetSavingsPlansCoverage
• ce:GetSavingsPlansUtilizationDetails
• ce:GetSavingsPlansPurchaseRecommendation
• ce:GetCostAndUsageComparisons
• ce:GetCostComparisonDrivers
• ce:GetAnomalies
• ce:GetCostAndUsage
• ce:GetCostAndUsageComparisons
• ce:GetCostAndUsageWithResources
• ce:GetDimensionValues
• ce:GetCostForecast
• ce:GetUsageForecast
• ce:GetTags
• ce:GetCostCategories

Cost Allocation Tags:

• ce:ListCostAllocationTags
• ce:ListCostAllocationTagBackfillHistory

Cost Category Definitions:

• ce:DescribeCostCategoryDefinition
• ce:ListCostCategoryDefinitions

Cost Optimization Hub:

• cost-optimization-hub:GetRecommendation
• cost-optimization-hub:ListRecommendations
• cost-optimization-hub:ListRecommendationSummaries

Compute Optimizer:

• compute-optimizer:GetAutoScalingGroupRecommendations
• compute-optimizer:GetEBSVolumeRecommendations
• compute-optimizer:GetEC2InstanceRecommendations
• compute-optimizer:GetECSServiceRecommendations
• compute-optimizer:GetRDSDatabaseRecommendations
• compute-optimizer:GetLambdaFunctionRecommendations
• compute-optimizer:GetEnrollmentStatus
• compute-optimizer:GetIdleRecommendations

AWS Budgets:

• budgets:ViewBudget

AWS Pricing:

• pricing:DescribeServices
• pricing:GetAttributeValues
• pricing:GetProducts

AWS Free Tier:

• freetier:GetFreeTierUsage

AWS Billing and Cost Management Pricing Calculator:

• bcm-pricing-calculator:GetPreferences
• bcm-pricing-calculator:GetWorkloadEstimate
• bcm-pricing-calculator:ListWorkloadEstimateUsage
• bcm-pricing-calculator:ListWorkloadEstimates

Storage Lens (Athena and S3):

• athena:StartQueryExecution
• athena:GetQueryExecution
• athena:GetQueryResults
• athena:CreateWorkGroup
• athena:GetWorkGroup
• athena:CreateDataCatalog
• athena:GetDataCatalog
• athena:GetDatabase
• athena:CreateTable
• athena:GetTableMetadata
• athena:ListDatabases
• athena:ListTableMetadata
• s3:GetObject
• s3:ListBucket
• s3:PutObject
• s3:GetBucketLocation
• s3:GetStorageLensConfiguration
• s3:ListStorageLensConfigurations
• s3:PutStorageLensConfiguration
• s3:GetStorageLensConfigurationTagging
• s3:PutStorageLensConfigurationTagging

AWS Billing Conductor:

• billingconductor:ListBillingGroups
• billingconductor:ListBillingGroupCostReports
• billingconductor:GetBillingGroupCostReport
• billingconductor:ListAccountAssociations
• billingconductor:ListPricingPlans
• billingconductor:ListPricingRules
• billingconductor:ListPricingRulesAssociatedToPricingPlan
• billingconductor:ListPricingPlansAssociatedWithPricingRule
• billingconductor:ListCustomLineItems
• billingconductor:ListCustomLineItemVersions
• billingconductor:ListResourcesAssociatedToCustomLineItem

Configuration

The server uses these key environment variables:

• AWS_PROFILE: Specifies the AWS profile to use from your AWS configuration file. If not provided, it defaults to the "default" profile.
• AWS_REGION: Determines the AWS region for API calls. Some APIs like Cost Explorer are only available in specific regions.

"env": {
  "AWS_PROFILE": "your-aws-profile",
  "AWS_REGION": "us-east-1"
}

Supported AWS Services

The server currently supports the following AWS services

1. Cost Explorer

   • get_reservation_purchase_recommendation
   • get_reservation_coverage
   • get_reservation_utilization
   • get_savings_plans_purchase_recommendation
   • get_savings_plans_utilization
   • get_savings_plans_coverage
   • get_savings_plans_details
   • get_cost_comparison_drivers
   • get_cost_and_usage_comparisons
   • get_anomalies
   • get_cost_and_usage
   • get_cost_and_usage_with_resources
   • get_dimension_values
   • get_cost_forecast
   • get_usage_forecast
   • get_tags
   • get_cost_categories

2. AWS Budgets

   • describe_budgets

3. AWS Free Tier

   • get_free_tier_usage

4. AWS Pricing

   • get_service_codes
   • get_service_attributes
   • get_attribute_values
   • get_products

5. Cost Optimization Hub

   • get_recommendation
   • list_recommendations
   • list_recommendation_summaries

6. Compute Optimizer

   • get_auto_scaling_group_recommendations
   • get_ebs_volume_recommendations
   • get_ec2_instance_recommendations
   • get_ecs_service_recommendations
   • get_rds_database_recommendations
   • get_lambda_function_recommendations
   • get_idle_recommendations
   • get_enrollment_status

7. Pricing Calculator

   • get-preferences
   • get-workload-estimate
   • list-workload-estimate-usage
   • list-workload-estimates

8. S3 Storage Lens

   • storage_lens_run_query (custom implementation using Athena)

9. AWS Billing Conductor

   • list_billing_groups
   • list_billing_group_cost_reports
   • get_billing_group_cost_report
   • list_account_associations
   • list_pricing_plans
   • list_pricing_rules
   • list_pricing_rules_associated_to_pricing_plan
   • list_pricing_plans_associated_with_pricing_rule
   • list_custom_line_items
   • list_custom_line_item_versions
   • list_resources_associated_to_custom_line_item

10. Cost Allocation Tags

    • list_cost_allocation_tags
    • list_cost_allocation_tag_backfill_history

11. Cost Category Definitions

    • describe_cost_category_definition
    • list_cost_category_definitions