{"id":7025,"library":"awslabs-billing-cost-management-mcp-server","title":"AWS Billing and Cost Management MCP Server","description":"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.","status":"active","version":"0.0.17","language":"en","source_language":"en","source_url":"https://github.com/awslabs/mcp","tags":["aws","billing","cost management","finops","mcp","ai agents","boto3","server"],"install":[{"cmd":"pip install awslabs-billing-cost-management-mcp-server","lang":"bash","label":"PyPI installation (requires uv/uvx for execution)"},{"cmd":"uvx awslabs.billing-cost-management-mcp-server@latest","lang":"bash","label":"Recommended execution via uvx (requires uv)"}],"dependencies":[{"reason":"Requires Python 3.10 or newer.","package":"python","optional":false},{"reason":"Recommended for installation and execution via `uvx`.","package":"uv","optional":false},{"reason":"Underlying AWS SDK for Python, wrapped by this server.","package":"boto3","optional":false}],"imports":[{"note":"The interaction model is client-server through the MCP protocol, not direct Python module imports.","symbol":"Server","correct":"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."}],"quickstart":{"code":"import os\n\n# Prerequisites: Install uv (e.g., curl -LsSf https://astral.sh/uv/install.sh | sh)\n# Ensure AWS credentials are configured (e.g., via ~/.aws/credentials or environment variables)\n# Minimum IAM permissions for Cost Explorer (ce:*), Budgets (budgets:*), Compute Optimizer (compute-optimizer:*)\n\n# Example of running the server via uvx and configuring an MCP client (like Amazon Q Developer CLI)\n# This code snippet demonstrates how to run the server in a way that an MCP client can connect.\n# It's not a direct Python import/call, but a shell command typically executed to start the server.\n\n# Set environment variables for AWS credentials if not using default profile\n# os.environ['AWS_ACCESS_KEY_ID'] = os.environ.get('AWS_ACCESS_KEY_ID', 'YOUR_AWS_ACCESS_KEY_ID')\n# os.environ['AWS_SECRET_ACCESS_KEY'] = os.environ.get('AWS_SECRET_ACCESS_KEY', 'YOUR_AWS_SECRET_ACCESS_KEY')\n# os.environ['AWS_SESSION_TOKEN'] = os.environ.get('AWS_SESSION_TOKEN', '') # Optional for temporary credentials\nos.environ['AWS_REGION'] = os.environ.get('AWS_REGION', 'us-east-1')\nos.environ['AWS_PROFILE'] = os.environ.get('AWS_PROFILE', 'default')\n\nprint(\"Starting AWS Billing and Cost Management MCP Server...\")\nprint(\"Run 'uvx awslabs.billing-cost-management-mcp-server@latest' in your terminal.\")\nprint(\"Then, configure your MCP client (e.g., Amazon Q Developer CLI) to connect.\")\nprint(\"Example client configuration for ~/.aws/amazonq/mcp.json:\")\nprint(\"{\")\nprint(\"  \\\"mcpServers\\\": {\")\nprint(\"    \\\"awslabs.billing-cost-management-mcp-server\\\": {\")\nprint(\"      \\\"command\\\": \\\"uvx\\\",\")\nprint(\"      \\\"args\\\": [ \\\"awslabs.billing-cost-management-mcp-server@latest\\\" ],\")\nprint(\"      \\\"env\\\": {\")\nprint(\"        \\\"AWS_PROFILE\\\": \\\"\" + os.environ['AWS_PROFILE'] + \"\\\",\")\nprint(\"        \\\"AWS_REGION\\\": \\\"\" + os.environ['AWS_REGION'] + \"\\\"\")\nprint(\"      },\")\nprint(\"      \\\"disabled\\\": false,\")\nprint(\"      \\\"autoApprove\\\": []\")\nprint(\"    }\")\nprint(\"  }\")\nprint(\"}\")","lang":"python","description":"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."},"warnings":[{"fix":"Migrate your MCP client configurations to use `awslabs.billing-cost-management-mcp-server` instead of the deprecated servers. [8, 9]","message":"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]","severity":"breaking","affected_versions":"<=0.0.17"},{"fix":"Be aware of AWS Cost Explorer API pricing and other relevant service API pricing. Monitor your AWS bill for API usage. [6, 8]","message":"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]","severity":"gotcha","affected_versions":"All versions"},{"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]","message":"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]","severity":"bug","affected_versions":"<=0.0.17"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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]","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]","error":"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..."},{"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.","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.","error":"Error: Failed to connect to the MCP server. Ensure the server is running and configured correctly."},{"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]","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]","error":"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"}]}