AWS Cost Explorer MCP Server

0.0.21 · active · verified Thu Apr 16

The `awslabs-cost-explorer-mcp-server` is a Python-based server application designed to analyze AWS costs and usage data by interacting with the AWS Cost Explorer API. Currently at version `0.0.21`, it provides a web interface for cost analysis and is primarily intended for deployment as a standalone service, often via Docker or AWS CDK, rather than as an embedded library. Its release cadence is infrequent, typical for experimental or early-stage AWS Labs projects.

Common errors

```
botocore.exceptions.NoCredentialsError: Unable to locate credentials
```
cause The server attempted to make an AWS API call (e.g., to Cost Explorer) but could not find any valid AWS credentials configured in the environment or standard locations.

fix Configure AWS credentials using environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`), an AWS config file (`~/.aws/credentials`), or by deploying on an EC2 instance/ECS task with an attached IAM role.
```
OSError: [Errno 98] Address already in use
```
cause The Flask development server (or any other process) tried to start on a port that is already in use by another application.

fix Change the port the server tries to run on (e.g., `app.run(port=5001)` in Python, or `flask run --port 5001` from the shell), or terminate the process currently using the desired port.
```
ModuleNotFoundError: No module named 'awscostexplorer.mcp_server.app'
```
cause The `awslabs-cost-explorer-mcp-server` package is not installed, or the `FLASK_APP` environment variable (if using `flask run`) is incorrectly set, preventing Flask from finding the application entry point.

fix Ensure the package is installed with `pip install awslabs-cost-explorer-mcp-server`. If running with `flask run`, set `FLASK_APP=awscostexplorer.mcp_server.app` before execution.

Warnings

breaking As a `0.0.x` version, the API and internal structure of the `awslabs-cost-explorer-mcp-server` may not be stable. Backward incompatible changes could occur in minor or patch releases.
Fix: Review release notes for each update. Pin dependencies to specific patch versions in production environments.
gotcha The server relies heavily on correct AWS credentials and IAM permissions to access the Cost Explorer API and other AWS services. Incorrect or missing credentials/permissions are a very common source of errors.
Fix: Ensure your environment has valid `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION` (or equivalent `~/.aws/credentials` setup, or IAM role for EC2/ECS). Grant necessary `ce:*` and `tag:*` permissions, and potentially `ec2:DescribeInstances` etc. as needed by the server's logic.
gotcha This library is primarily designed as a server application to be run directly (e.g., via `flask run`, Docker, or AWS CDK) rather than being imported and used as a traditional Python library within other applications. While programmatic embedding is possible, it's not the main use case.
Fix: Consider running the server as a standalone service and interacting with its web interface, rather than trying to embed its internal components directly into custom Python scripts, unless explicitly developing extensions for it.

Install

pip install awslabs-cost-explorer-mcp-server Install library

Imports

create_app
```
from awscostexplorer.mcp_server.app import create_app
```
This is the primary entry point for the Flask application if embedding programmatically. Typical usage is to run the server directly via `flask run` or a WSGI server.

Quickstart

Installs the server and demonstrates how to run it locally using Flask's development server. This quickstart programmatically starts the server; alternatively, you can use `export FLASK_APP=awscostexplorer.mcp_server.app && flask run` from your shell. Requires AWS credentials and a default region to be configured in the environment or via other boto3-supported methods.

import os
from awscostexplorer.mcp_server.app import create_app

# Set dummy environment variables if not already set, for illustration.
# In a real scenario, ensure valid AWS credentials are configured (e.g., ~/.aws/credentials,
# IAM roles, or actual environment variables like AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY).
os.environ['AWS_ACCESS_KEY_ID'] = os.environ.get('AWS_ACCESS_KEY_ID', 'DUMMY_KEY')
os.environ['AWS_SECRET_ACCESS_KEY'] = os.environ.get('AWS_SECRET_ACCESS_KEY', 'DUMMY_SECRET')
os.environ['AWS_SESSION_TOKEN'] = os.environ.get('AWS_SESSION_TOKEN', '') # Optional
os.environ['AWS_REGION'] = os.environ.get('AWS_REGION', 'us-east-1') # Default region

# Create the Flask application instance
app = create_app()

if __name__ == '__main__':
    # Run the Flask development server.
    # For production, use a WSGI server (e.g., Gunicorn, uWSGI) instead of app.run().
    print(f"\nStarting AWS Cost Explorer MCP Server (Flask dev server) on http://127.0.0.1:5000/")
    print("Ensure valid AWS credentials and region are configured (e.g., via environment variables or ~/.aws/credentials).")
    print("Access the UI at http://127.0.0.1:5000/ and check server logs for errors.\n")
    app.run(debug=True, port=5000)

view raw JSON →