AWS Billing and Cost Management MCP Server

0.0.17 · active · verified Thu Apr 16

The AWS Billing and Cost Management Model Context Protocol (MCP) server provides tools to analyze historical spending, identify cost optimization opportunities, and estimate new workload costs by wrapping boto3 SDK functions. Released by AWS Labs, it is currently at version 0.0.17 and is actively maintained, with updates released as part of the broader `awslabs/mcp` repository development.

Common errors

```
2025/08/26 04:06:28 [ERROR] mcp-client: Tool execution error tool=cost-explorer error=Input validation error: ['UnblendedCost'] is not valid under any of the given schemas Action: awslabs.billing-cost-management-mcp-serv...
```
cause This error, particularly 'Input validation error: ['UnblendedCost'] is not valid under any of the given schemas', indicates that the parameters or metrics requested for Cost Explorer are not compatible with the API's expectations or current configuration. [10]

fix Review the specific metrics and dimensions you are requesting in your natural language query. Ensure they are valid for AWS Cost Explorer. This might also be related to internal schema mismatches within the MCP server's mapping to the AWS API, which could require an update to the MCP server. Check the GitHub issues for known parameter validation problems. [10]
```
Error: Failed to connect to the MCP server. Ensure the server is running and configured correctly.
```
cause The MCP client (e.g., Amazon Q Developer CLI, Kiro, Claude Desktop) cannot establish a connection with the `awslabs-billing-cost-management-mcp-server`. This could be due to the server not running, incorrect client configuration, or network issues.

fix Verify that the MCP server is running by executing `uvx awslabs.billing-cost-management-mcp-server@latest` in a terminal. Check your MCP client's configuration file (e.g., `~/.aws/amazonq/mcp.json` for Amazon Q Developer CLI) for correct `command`, `args`, and `env` settings, especially `AWS_PROFILE` and `AWS_REGION`. Ensure no firewalls are blocking the connection if running across different hosts.
```
ClientError: An error occurred (AccessDeniedException) when calling the GetCostAndUsage operation: User: arn:aws:iam::123456789012:user/test-user is not authorized to perform ce:GetCostAndUsage on resource: arn:aws:iam::123456789012:user/test-user
```
cause The AWS credentials configured for the MCP server lack the necessary IAM permissions to access the AWS Billing and Cost Management APIs. The server uses the caller's AWS credentials to make API calls. [3, 4, 6]

fix Ensure the IAM role or user associated with your AWS credentials has sufficient permissions for the AWS services the MCP server interacts with (e.g., `ce:*` for Cost Explorer, `budgets:*` for Budgets, `compute-optimizer:*` for Compute Optimizer). Apply the principle of least privilege. [3, 4, 6]

Warnings

breaking The `awslabs.cost-analysis-mcp-server` and `awslabs.cost-explorer-mcp-server` are deprecated. Users should migrate to `awslabs-billing-cost-management-mcp-server` for broader cost analysis capabilities, including Cost Explorer, Budgets, and Cost Anomaly Detection. [8, 9]
Fix: Migrate your MCP client configurations to use `awslabs.billing-cost-management-mcp-server` instead of the deprecated servers. [8, 9]
gotcha Using the AWS Billing and Cost Management MCP server incurs AWS API charges. Each API call made by the server, by wrapping boto3 functions, results in charges to your AWS account. [6, 8]
Fix: Be aware of AWS Cost Explorer API pricing and other relevant service API pricing. Monitor your AWS bill for API usage. [6, 8]
bug The `get_reservation_coverage` operation within the `ri_performance` tool can fail with a `ValidationException` if `group_by` is specified. The underlying AWS GetReservationCoverage API requires `Granularity` and `GroupBy` to be mutually exclusive, but the server currently sends both. [13, 14]
Fix: Avoid using `group_by` when querying `get_reservation_coverage` with the `ri_performance` tool. Monitor the `awslabs/mcp` GitHub repository for updates and the resolution of issue #2933, as a pull request for this fix is pending. [14]

Install

pip install awslabs-billing-cost-management-mcp-server PyPI installation (requires uv/uvx for execution)
uvx awslabs.billing-cost-management-mcp-server@latest Recommended execution via uvx (requires uv)

Imports

Server

This library is primarily designed to be run as a server process and interacted with via the Model Context Protocol (MCP) by AI clients (e.g., Amazon Q Developer CLI), rather than being imported directly into user Python code for function calls. There is no standard direct import pattern for a 'Server' class for typical application integration.

The interaction model is client-server through the MCP protocol, not direct Python module imports.

Quickstart

This quickstart describes how to run the AWS Billing and Cost Management MCP server using `uvx` and provides an example configuration for an MCP client like Amazon Q Developer CLI. The server itself is designed to be run as a separate process, and AI clients then connect to it to leverage its capabilities via natural language queries. Ensure `uv` is installed and AWS credentials with appropriate permissions are configured.

import os

# Prerequisites: Install uv (e.g., curl -LsSf https://astral.sh/uv/install.sh | sh)
# Ensure AWS credentials are configured (e.g., via ~/.aws/credentials or environment variables)
# Minimum IAM permissions for Cost Explorer (ce:*), Budgets (budgets:*), Compute Optimizer (compute-optimizer:*)

# Example of running the server via uvx and configuring an MCP client (like Amazon Q Developer CLI)
# This code snippet demonstrates how to run the server in a way that an MCP client can connect.
# It's not a direct Python import/call, but a shell command typically executed to start the server.

# Set environment variables for AWS credentials if not using default profile
# os.environ['AWS_ACCESS_KEY_ID'] = os.environ.get('AWS_ACCESS_KEY_ID', 'YOUR_AWS_ACCESS_KEY_ID')
# os.environ['AWS_SECRET_ACCESS_KEY'] = os.environ.get('AWS_SECRET_ACCESS_KEY', 'YOUR_AWS_SECRET_ACCESS_KEY')
# os.environ['AWS_SESSION_TOKEN'] = os.environ.get('AWS_SESSION_TOKEN', '') # Optional for temporary credentials
os.environ['AWS_REGION'] = os.environ.get('AWS_REGION', 'us-east-1')
os.environ['AWS_PROFILE'] = os.environ.get('AWS_PROFILE', 'default')

print("Starting AWS Billing and Cost Management MCP Server...")
print("Run 'uvx awslabs.billing-cost-management-mcp-server@latest' in your terminal.")
print("Then, configure your MCP client (e.g., Amazon Q Developer CLI) to connect.")
print("Example client configuration for ~/.aws/amazonq/mcp.json:")
print("{")
print("  \"mcpServers\": {")
print("    \"awslabs.billing-cost-management-mcp-server\": {")
print("      \"command\": \"uvx\",")
print("      \"args\": [ \"awslabs.billing-cost-management-mcp-server@latest\" ],")
print("      \"env\": {")
print("        \"AWS_PROFILE\": \"" + os.environ['AWS_PROFILE'] + "\",")
print("        \"AWS_REGION\": \"" + os.environ['AWS_REGION'] + "\"")
print("      },")
print("      \"disabled\": false,")
print("      \"autoApprove\": []")
print("    }")
print("  }")
print("}")

view raw JSON →