AWS Billing and Cost Management MCP Server

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, plus their configured enforcement actions and alert notifications (per-budget or account-wide)
• 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 performance: Analyze how much eligible spend existing plans cover and how much of their commitment is consumed over a lookback window
• Savings Plans inventory: Describe the plans an account owns with their state, term, payment option, commitment, and expiry, including the queued, returned, and payment-failed plans that Cost Explorer does not report; a large inventory is offloaded to session SQL to save tokens
• Savings Plans rates and offerings: Look up the rates locked in on plans already owned, and the offerings available to purchase with their rates, to compare terms and payment options against real numbers. A large result from any of these describe operations is offloaded to session SQL (queryable with the session-sql tool) to save tokens
• Savings Plans recommendations: Get personalized purchase recommendations based on usage patterns, the hourly data-points behind a recommendation, and the history of when recommendations were generated
• Savings Plans purchase analysis: Run Purchase Analyzer what-if analyses — maximum savings, a specific commitment, or a target average coverage — and retrieve the projected cost, coverage, and utilization once an analysis completes

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
• Billing transfer preferences: Check whether billing groups are created automatically for new end customers in a two-level billing transfer, and which pricing plan they use

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

AWS Invoicing

• Invoice summaries: List invoice-level details (invoice ID, type, billing period, issued/due dates, issuing entity, and amounts with discount/tax/fee breakdowns across base, tax, and payment currencies) for an account (filtered by month or date range) or a single invoice
• Invoice units: List and retrieve invoice unit definitions (groups of accounts that receive a separate invoice, with their receiver account and linked-account rules), filtered by name, receiver, or member account; and fetch invoice receiver profiles (legal name, address, tax registration number) for a set of accounts
• Procurement portal preferences: List and retrieve procurement portal connections (SAP Business Network, Coupa) and e-invoice delivery / purchase-order retrieval settings

AWS Billing Preferences

• Discount sharing configuration: Retrieve which member accounts participate in the Reserved Instance / Savings Plans discount pool and in credit sharing, whether newly created accounts join automatically, and whether sharing is open — the authoritative answer to "is this account excluded from commitment sharing", which cannot be inferred from RI/SP coverage data
• Sharing history: The per-billing-period record of those settings, for reconciling a closed billing period against the sharing state that was actually in force at the time
• Billing alerts: Whether billing alerts are enabled

AWS Enterprise Support

• Enterprise Support charge summary: Retrieve a billing period's Enterprise Support charge with the Support-eligible spend it was calculated from, the effective pricing plan, and any applied discounts
• Support contract details: Review the contract terms that govern how a billing period's charge is allocated, including the allocation method, Reserved Instance and Savings Plan treatment, and the payer accounts covered
• Per-account charge breakdown: Break a billing period's charge down by linked account with prorated Support-eligible spend, subscription periods, and per-service spend

AWS Business Support

• Account charges: Retrieve a billing month's Business Support charges per account, with the Support-eligible spend each charge was calculated from, the tiered charge breakdown, any applied discount, and the profile-wide totals. The current month is returned as an estimate
• Subscription history: Review the Support plan contracts in effect for a billing month or a date range, including the plan and the contract start and end dates

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:GetSavingsPlanPurchaseRecommendationDetails
• ce:StartSavingsPlansPurchaseRecommendationGeneration
• ce:ListSavingsPlansPurchaseRecommendationGeneration
• ce:StartCommitmentPurchaseAnalysis
• ce:GetCommitmentPurchaseAnalysis
• ce:ListCommitmentPurchaseAnalyses
• ce:GetCostAndUsageComparisons
• ce:GetCostComparisonDrivers
• ce:GetAnomalies
• ce:GetAnomalyMonitors
• ce:GetAnomalySubscriptions
• ce:GetCostAndUsage
• ce:GetCostAndUsageComparisons
• ce:GetCostAndUsageWithResources
• ce:GetDimensionValues
• ce:GetCostForecast
• ce:GetUsageForecast
• ce:GetTags
• ce:GetCostCategories

Savings Plans:

• savingsplans:DescribeSavingsPlans
• savingsplans:DescribeSavingsPlanRates
• savingsplans:DescribeSavingsPlansOfferings
• savingsplans:DescribeSavingsPlansOfferingRates

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
• cost-optimization-hub:ListEfficiencyMetrics
• cost-optimization-hub:ListEnrollmentStatuses
• cost-optimization-hub:GetPreferences

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

Compute Optimizer Automation:

• aco-automation:GetAutomationEvent
• aco-automation:GetAutomationRule
• aco-automation:GetEnrollmentConfiguration
• aco-automation:ListAccounts
• aco-automation:ListAutomationEvents
• aco-automation:ListAutomationEventSteps
• aco-automation:ListAutomationEventSummaries
• aco-automation:ListAutomationRules
• aco-automation:ListRecommendedActions
• aco-automation:ListRecommendedActionSummaries
• aco-automation:ListAutomationRulePreview
• aco-automation:ListAutomationRulePreviewSummaries
• aco-automation:ListTagsForResource
• ec2:DescribeVolumes (required by ListRecommendedActions and ListAutomationRulePreview)

AWS Budgets:

• budgets:ViewBudget (also covers budget notifications, per-budget and account-wide, and budget performance history)
• budgets:DescribeBudgetActionsForBudget (required for budget actions by budget name)
• budgets:DescribeBudgetActionsForAccount (required for account-wide budget actions)

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
• glue:GetDatabase
• glue:CreateDatabase
• glue:GetTable
• glue:CreateTable
• glue:GetPartitions (Athena checks it, with glue:UpdateTable, for ALTER TABLE ... SET LOCATION)
• glue:UpdateTable (points the table at another day's report folder)
• 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
• billingconductor:GetBillingTransferPreference

AWS Invoicing:

• invoicing:ListInvoiceSummaries
• invoicing:ListInvoiceUnits
• invoicing:GetInvoiceUnit
• invoicing:BatchGetInvoiceProfile
• invoicing:ListProcurementPortalPreferences
• invoicing:GetProcurementPortalPreference

AWS Billing:

• billing:GetBillingView
• billing:ListBillingViews
• billing:ListSourceViewsForBillingView
• billing:GetResourcePolicy
• billing:GetCredits
• billing:GetCreditAllocationHistory
• billing:GetBillingPreferences
• billing:GetEnterpriseSupportChargeSummary
• billing:GetEnterpriseSupportContractDetails
• billing:ListEnterpriseSupportLinkedAccountCharges
• billing:ListBusinessSupportAccountCharges
• billing:ListBusinessSupportSubscriptionHistory
• billing:ListBillingViewSegments

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

Pagination

List tools take max_items (the total number of items to return) and next_token. Without max_items a tool fetches every page; with it, the tool stops before a page that could take the result past max_items (the first page is always returned). ri-performance get_reservation_utilization grouped by SUBSCRIPTION_ID takes max_pages instead of max_items: its next_token only works with the same page size, so it returns whole pages of 500 groups; omit max_pages to fetch every page. Billing Conductor get-billing-group-cost-report requests pages of 200 to 300 results, the range the service accepts, so a max_items below 200 can return up to 200. next_token in a response is the AWS service's own continuation token: pass it back, with every other parameter unchanged, to get the next items.

A response that stops before the end of the data leads with complete_dataset: false and a warning, and every paginated response carries a pagination block:

{"complete_dataset": false, "warning": "Partial data: ...", "pagination": {"complete_dataset": false, "has_more": true, "next_token": "<service token>", "items_returned": 5000}, "...": "data"}

The pagination block comes before the data, so it is read before the data itself.

has_more is true only when next_token can continue the result. A result can be partial with has_more: false, for example when a page failed in a way that invalidates the token or when one region of a multi-region call failed; the warning then says how to recover.

One call also stops paging, on a page boundary, when it reaches the server's time limit. The result is then partial and continues with next_token.

Environment variable	Default	Limit
BCM_MCP_PAGINATION_MAX_SECONDS	300	Seconds one call spends paging

A rejected or expired next_token returns error_type: invalid_next_token; call again without next_token to restart.

Error responses

Tool errors are returned with isError: true and a JSON body that includes:

Field	Description
status	Always error
error_type	Stable classification. AWS API errors pass the AWS error code through (ThrottlingException, AccessDeniedException, ...); local errors use lowercase values (validation_error, no_results, invalid_operation, ...)
message	Human-readable explanation
retry_strategy	What the caller should do next: retry_same_request, modify_request, or do_not_retry
hint	Optional fixed recovery guidance

retry_strategy is derived from error_type:

retry_strategy	error_type values
retry_same_request	Throttling (ThrottlingException, Throttling, ThrottledException, TooManyRequestsException, RequestLimitExceeded, LimitExceededException, RequestThrottled, RequestThrottledException, ProvisionedThroughputExceededException, TransactionInProgressException, PriorRequestNotComplete, EC2ThrottledException, SlowDown, BandwidthLimitExceeded, throttling_error), aws_connection_error (transient botocore errors only: connection failures, no client-side request capacity, response body cut short or corrupted; other botocore errors set their own retry_strategy, see below), server-side errors (InternalServerException, InternalErrorException, InternalError, IDPCommunicationError, ServiceUnavailable, service_unavailable, ...), timeouts (unknown_timeouterror), and any otherwise unmapped AWS error with an HTTP 5xx status
modify_request	validation_error, invalid_operation, invalid_parameter_value, ValidationException, InvalidParameter*, InvalidInputException, InvalidNextTokenException, ExpiredNextTokenException, InvalidRequestException, BadRequestException, BillExpirationException, RequestChangedException, invalid_next_token, no_results, ResourceNotFoundException, resource_not_found, NotFoundException, not_found
do_not_retry	AccessDenied*, access_denied, UnauthorizedOperation, UnauthorizedException, AuthFailure, OptInRequiredException, opt_in_required, enrollment_error, DataUnavailableException, and any missing or unrecognized error_type

A tool can override the mapping for a specific error by passing retry_strategy= and hint= to format_response. Session SQL errors from invalid queries are modify_request, and when every region of a multi-region call fails, retry_strategy is combined from each region's own error. A botocore ParamValidationError (malformed request parameters, rejected before any request is sent) is a validation_error. aws_connection_error is retry_same_request only for transient failures: botocore's ConnectionError and HTTPClientError classes (such as EndpointConnectionError and ReadTimeoutError), CapacityNotAvailableError (raised by botocore's client-side token bucket when no request capacity is available; kept retryable), and a response body cut short or corrupted in transit (IncompleteReadError, ChecksumError, FlexibleChecksumError); boto_error_type names the botocore class. Every other botocore error keeps error_type: aws_connection_error but sets its own retry_strategy: modify_request for botocore's other argument checks (UnknownParameterError, RangeError, ...), and do_not_retry for credential and configuration errors (NoCredentialsError, CredentialRetrievalError from a failed credential_process, an expired SSO token, NoRegionError, ProfileNotFound, ...) and any other SDK-side failure, since a retry fails the same way. The full mapping is in utilities/error_contract.py.

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_anomaly_monitors
   • get_anomaly_subscriptions
   • 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
   • describe_budget_actions (DescribeBudgetActionsForBudget / DescribeBudgetActionsForAccount)
   • describe_budget_notifications (DescribeNotificationsForBudget / DescribeBudgetNotificationsForAccount)
   • describe_budget_performance_history

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
   • list_efficiency_metrics
   • list_enrollment_statuses
   • get_preferences

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

7. Compute Optimizer Automation

   • get_automation_event
   • get_automation_rule
   • get_enrollment_configuration
   • list_accounts
   • list_automation_events
   • list_automation_event_steps
   • list_automation_event_summaries
   • list_automation_rules
   • list_recommended_actions
   • list_recommended_action_summaries
   • list_automation_rule_preview
   • list_automation_rule_preview_summaries
   • list_tags_for_resource

8. Pricing Calculator

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

9. S3 Storage Lens

   • storage_lens_run_query (custom implementation using Athena)

10. 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
• get_billing_transfer_preference

11. Cost Allocation Tags

    • list_cost_allocation_tags
    • list_cost_allocation_tag_backfill_history

12. Cost Category Definitions

    • describe_cost_category_definition
    • list_cost_category_definitions

13. AWS Invoicing

    • invoicing tool: list_invoice_summaries
    • invoice-units tool: list_invoice_units, get_invoice_unit, batch_get_invoice_profile
    • procurement-preferences tool: list_procurement_portal_preferences, get_procurement_portal_preference

14. AWS Credits

    • credits tool: get_credits, get_credit_allocation_history

15. AWS Billing Preferences

    • get-billing-preferences

16. AWS Enterprise Support

    • enterprise-support tool: get_charge_summary, get_contract_details, list_linked_account_charges

17. AWS Business Support

    • business-support tool: list_account_charges, list_subscription_history

18. AWS Billing Views

    • get-billing-view: retrieve metadata for a specific billing view
    • list-billing-views: list billing views available for a given time period
    • list-source-views-for-billing-view: list source views that a custom billing view is built from
    • get-resource-policy: retrieve the resource-based policy attached to a billing view
    • list-billing-view-segments: list billing view segments over a time period to determine billing domain (BILLABLE vs PRO_FORMA) and account relationships