Features

• Amazon EC2 Spend Analysis: View detailed breakdowns of EC2 spending for the last day
• Amazon Bedrock Spend Analysis: View breakdown by region, users and models over the last 30 days
• Service Spend Reports: Analyze spending across all AWS services for the last 30 days
• Detailed Cost Breakdown: Get granular cost data by day, region, service, and instance type
• Interactive Interface: Use Claude to query your cost data through natural language

Requirements

• Python 3.12
• AWS credentials with Cost Explorer access
• Anthropic API access (for Claude integration)
• [Optional] Amazon Bedrock access (for LangGraph Agent)
• [Optional] Amazon EC2 for running a remote MCP server

Installation

1. Install uv:

   # On macOS and Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh
   

   # On Windows
   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
   

   Additional installation options are documented here

2. Clone this repository: (assuming this will be updated to point to aws-samples?)

   git clone https://github.com/aarora79/aws-cost-explorer-mcp.git
   cd aws-cost-explorer-mcp
   

3. Set up the Python virtual environment and install dependencies:

   uv venv --python 3.12 && source .venv/bin/activate && uv pip install --requirement pyproject.toml
   

4. Configure your AWS credentials:

   mkdir -p ~/.aws
   # Set up your credentials in ~/.aws/credentials and ~/.aws/config
   

   If you useAWS IAM Identity Center, follow the docs to configure your short-term credentials

Usage

Prerequisites

1. Setup model invocation logs in Amazon CloudWatch.
2. Ensure that the IAM user/role being used has full read-only access to Amazon Cost Explorer and Amazon CloudWatch, this is required for the MCP server to retrieve data from these services. See here and here for sample policy examples that you can use & modify as per your requirements.
3. To allow your MCP server to access AWS spend information from other accounts set the the CROSS_ACCOUNT_ROLE_NAME parameter while starting the server and now you can provide the account AWS account id for another account while interacting with your agent and then agent will pass the account id to the server.

Local setup

Uses stdio as a transport for MCP, both the MCP server and client are running on your local machine.

Starting the Server (local)

Run the server using:

export MCP_TRANSPORT=stdio
export BEDROCK_LOG_GROUP_NAME=YOUR_BEDROCK_CW_LOG_GROUP_NAME
export CROSS_ACCOUNT_ROLE_NAME=ROLE_NAME_FOR_THE_ROLE_TO_ASSUME_IN_OTHER_ACCOUNTS # can be ignored if you do not want AWS spend info from other accounts
python server.py

Claude Desktop Configuration

There are two ways to configure this tool with Claude Desktop:

Option 1: Using Docker

Add the following to your Claude Desktop configuration file. The file can be found out these paths depending upon you operating system.

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json.
• Windows: %APPDATA%\Claude\claude_desktop_config.json.
• Linux: ~/.config/Claude/claude_desktop_config.json.

{
  "mcpServers": {
    "aws-cost-explorer": {
      "command": "docker",
      "args": [ "run", "-i", "--rm", "-e", "AWS_ACCESS_KEY_ID", "-e", "AWS_SECRET_ACCESS_KEY", "-e", "AWS_REGION", "-e", "BEDROCK_LOG_GROUP_NAME", "-e", "MCP_TRANSPORT", "-e", "CROSS_ACCOUNT_ROLE_NAME", "aws-cost-explorer-mcp:latest" ],
      "env": {
        "AWS_ACCESS_KEY_ID": "YOUR_ACCESS_KEY_ID",
        "AWS_SECRET_ACCESS_KEY": "YOUR_SECRET_ACCESS_KEY",
        "AWS_REGION": "us-east-1",
        "BEDROCK_LOG_GROUP_NAME": "YOUR_CLOUDWATCH_BEDROCK_MODEL_INVOCATION_LOG_GROUP_NAME",
        "CROSS_ACCOUNT_ROLE_NAME": "ROLE_NAME_FOR_THE_ROLE_TO_ASSUME_IN_OTHER_ACCOUNTS",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

IMPORTANT: Replace YOUR_ACCESS_KEY_ID and YOUR_SECRET_ACCESS_KEY with your actual AWS credentials. Never commit actual credentials to version control.

Option 2: Using UV (without Docker)

If you prefer to run the server directly without Docker, you can use UV:

{
  "mcpServers": {
    "aws_cost_explorer": {
      "command": "uv",
      "args": [
          "--directory",
          "/path/to/aws-cost-explorer-mcp-server",
          "run",
          "server.py"
      ],
      "env": {
        "AWS_ACCESS_KEY_ID": "YOUR_ACCESS_KEY_ID",
        "AWS_SECRET_ACCESS_KEY": "YOUR_SECRET_ACCESS_KEY",
        "AWS_REGION": "us-east-1",
        "BEDROCK_LOG_GROUP_NAME": "YOUR_CLOUDWATCH_BEDROCK_MODEL_INVOCATION_LOG_GROUP_NAME",
        "CROSS_ACCOUNT_ROLE_NAME": "ROLE_NAME_FOR_THE_ROLE_TO_ASSUME_IN_OTHER_ACCOUNTS",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Make sure to replace the directory path with the actual path to your repository on your system.

Remote setup

Uses sse as a transport for MCP, the MCP servers on EC2 and the client is running on your local machine. Note that Claude Desktop does not support remote MCP servers at this time (see this GitHub issue).

Starting the Server (remote)

You can start a remote MCP server on Amazon EC2 by following the same instructions as above. Make sure to set the MCP_TRANSPORT as sse (server side events) as shown below. Note that the MCP uses JSON-RPC 2.0 as its wire format, therefore the protocol itself does not include authorization and authentication (see this GitHub issue), do not send or receive sensitive data over MCP.

Run the server using:

export MCP_TRANSPORT=sse
export BEDROCK_LOG_GROUP_NAME=YOUR_BEDROCK_CW_LOG_GROUP_NAME
export CROSS_ACCOUNT_ROLE_NAME=ROLE_NAME_FOR_THE_ROLE_TO_ASSUME_IN_OTHER_ACCOUNTS # can be ignored if you do not want AWS spend info from other accounts
python server.py

1. The MCP server will start listening on TCP port 8000.
2. Configure an ingress rule in the security group associated with your EC2 instance to allow access to TCP port 8000 from your local machine (where you are running the MCP client/LangGraph based app) to your EC2 instance.

Also see section on running a "secure" remote MCP server i.e. a server to which your MCP clients can connect over HTTPS.

Testing with a CLI MCP client

You can test your remote MCP server with the mcp_sse_client.py script. Running this script will print the list of tools available from the MCP server and an output for the get_bedrock_daily_usage_stats tool.

# set the hostname for your MCP server
MCP_SERVER_HOSTNAME=YOUR_MCP_SERVER_EC2_HOSTNAME
# or localhost if your MCP server is running locally
# MCP_SERVER_HOSTNAME=localhost 
AWS_ACCOUNT_ID=AWS_ACCOUNT_ID_TO_GET_INFO_ABOUT # if set to empty or if the --aws-account-id switch is not specified then it gets the info about the AWS account MCP server is running in
python mcp_sse_client.py --host $MCP_SERVER_HOSTNAME --aws-account-id $AWS_ACCOUNT_ID

Testing with Chainlit app

The app.py file in this repo provides a Chainlit app (chatbot) which creates a LangGraph agent that uses the LangChain MCP Adapter to import the tools provided by the MCP server as tools in a LangGraph Agent. The Agent is then able to use an LLM to respond to user questions and use the tools available to it as needed. Thus if the user asks a question such as "What was my Bedrock usage like in the last one week?" then the Agent will use the t