Skip to content
Back to search

aws-cost-explorer-mcp-server

MCP server for understanding AWS spend

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aarora79--aws-cost-explorer-mcp-server/badge.svg)](/listings/aarora79--aws-cost-explorer-mcp-server)

HTML

<a href="/listings/aarora79--aws-cost-explorer-mcp-server"><img src="/api/listings/aarora79--aws-cost-explorer-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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](https://docs.astral.sh/uv/getting-started/installation/)

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](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html) to configure your short-term credentials

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 362 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # AWS Cost Explorer and Amazon Bedrock Model Invocation Logs MCP Server & Client
  2. An MCP server for getting AWS spend data via Cost Explorer and Amazon Bedrock usage data via [`Model invocation logs`](https://docs.aws.amazon.com/bedrock/latest/userguide/model-invocation-logging.html) in Amazon Cloud Watch through [Anthropic's MCP (Model Control Protocol)](https://www.anthropic.com/news/model-context-protocol). See section on ["secure" remote MCP server](#secure-remote-mcp-server) to see how you can run your MCP server over HTTPS.
  3. ```mermaid
  4. flowchart LR
  5. User([User]) --> UserApp[User Application]
  6. UserApp --> |Queries| Host[Host]
  7. subgraph "Claude Desktop"
  8. Host --> MCPClient[MCP Client]
  9. end
  10. MCPClient --> |MCP Protocol over HTTPS| MCPServer[AWS Cost Explorer MCP Server]
  11. subgraph "AWS Services"
  12. MCPServer --> |API Calls| CostExplorer[(AWS Cost Explorer)]
  13. MCPServer --> |API Calls| CloudWatchLogs[(AWS CloudWatch Logs)]
  14. end
  15. ```
  16. You can run the MCP server locally and access it via the Claude Desktop or you could also run a Remote MCP server on Amazon EC2 and access it via a MCP client built into a LangGraph Agent.
  17. 🚨You can also use this MCP server to get AWS spend information from other accounts as long as the IAM role used by the MCP server can assume roles in those other accounts🚨
  18. ### Demo video
  19. [![AWS Cost Explorer MCP Server Deep Dive](https://img.youtube.com/vi/WuVOmYLRFmI/maxresdefault.jpg)](https://youtu.be/WuVOmYLRFmI)
  20. ## Overview
  21. This tool provides a convenient way to analyze and visualize AWS cloud spending data using Anthropic's Claude model as an interactive interface. It functions as an MCP server that exposes AWS Cost Explorer API functionality to Claude Desktop, allowing you to ask questions about your AWS spend in natural language.
  22. ## Features
  23. - **Amazon EC2 Spend Analysis**: View detailed breakdowns of EC2 spending for the last day
  24. - **Amazon Bedrock Spend Analysis**: View breakdown by region, users and models over the last 30 days
  25. - **Service Spend Reports**: Analyze spending across all AWS services for the last 30 days
  26. - **Detailed Cost Breakdown**: Get granular cost data by day, region, service, and instance type
  27. - **Interactive Interface**: Use Claude to query your cost data through natural language
  28. ## Requirements
  29. - Python 3.12
  30. - AWS credentials with Cost Explorer access
  31. - Anthropic API access (for Claude integration)
  32. - [Optional] Amazon Bedrock access (for LangGraph Agent)
  33. - [Optional] Amazon EC2 for running a remote MCP server
  34. ## Installation
  35. 1. Install `uv`:
  36. ```bash
  37. # On macOS and Linux
  38. curl -LsSf https://astral.sh/uv/install.sh | sh
  39. ```
  40. ```powershell
  41. # On Windows
  42. powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  43. ```
  44. Additional installation options are documented [here](https://docs.astral.sh/uv/getting-started/installation/)
  45. 2. Clone this repository: (assuming this will be updated to point to aws-samples?)
  46. ```
  47. git clone https://github.com/aarora79/aws-cost-explorer-mcp.git
  48. cd aws-cost-explorer-mcp
  49. ```
  50. 3. Set up the Python virtual environment and install dependencies:
  51. ```
  52. uv venv --python 3.12 && source .venv/bin/activate && uv pip install --requirement pyproject.toml
  53. ```
  54. 4. Configure your AWS credentials:
  55. ```
  56. mkdir -p ~/.aws
  57. # Set up your credentials in ~/.aws/credentials and ~/.aws/config
  58. ```
  59. If you useAWS IAM Identity Center, follow the [docs](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html) to configure your short-term credentials
  60. ## Usage
  61. ### Prerequisites
  62. 1. Setup [model invocation logs](https://docs.aws.amazon.com/bedrock/latest/userguide/model-invocation-logging.html#setup-cloudwatch-logs-destination) in Amazon CloudWatch.
  63. 1. 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.
  64. See [here](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/billing-example-policies.html) and [here](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsReadOnlyAccess.html) for sample policy examples that you can use & modify as per your requirements.
  65. 1. 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.
  66. ### Local setup
  67. Uses `stdio` as a transport for MCP, both the MCP server and client are running on your local machine.
  68. #### Starting the Server (local)
  69. Run the server using:
  70. ```
  71. export MCP_TRANSPORT=stdio
  72. export BEDROCK_LOG_GROUP_NAME=YOUR_BEDROCK_CW_LOG_GROUP_NAME
  73. 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
  74. python server.py
  75. ```
  76. #### Claude Desktop Configuration
  77. There are two ways to configure this tool with Claude Desktop:
  78. ##### Option 1: Using Docker
  79. Add the following to your Claude Desktop configuration file. The file can be found out these paths depending upon you operating system.
  80. - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json.
  81. - Windows: %APPDATA%\Claude\claude_desktop_config.json.
  82. - Linux: ~/.config/Claude/claude_desktop_config.json.
  83. ```json
  84. {
  85. "mcpServers": {
  86. "aws-cost-explorer": {
  87. "command": "docker",
  88. "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" ],
  89. "env": {
  90. "AWS_ACCESS_KEY_ID": "YOUR_ACCESS_KEY_ID",
  91. "AWS_SECRET_ACCESS_KEY": "YOUR_SECRET_ACCESS_KEY",
  92. "AWS_REGION": "us-east-1",
  93. "BEDROCK_LOG_GROUP_NAME": "YOUR_CLOUDWATCH_BEDROCK_MODEL_INVOCATION_LOG_GROUP_NAME",
  94. "CROSS_ACCOUNT_ROLE_NAME": "ROLE_NAME_FOR_THE_ROLE_TO_ASSUME_IN_OTHER_ACCOUNTS",
  95. "MCP_TRANSPORT": "stdio"
  96. }
  97. }
  98. }
  99. }
  100. ```
  101. > **IMPORTANT**: Replace `YOUR_ACCESS_KEY_ID` and `YOUR_SECRET_ACCESS_KEY` with your actual AWS credentials. Never commit actual credentials to version control.
  102. ##### Option 2: Using UV (without Docker)
  103. If you prefer to run the server directly without Docker, you can use UV:
  104. ```json
  105. {
  106. "mcpServers": {
  107. "aws_cost_explorer": {
  108. "command": "uv",
  109. "args": [
  110. "--directory",
  111. "/path/to/aws-cost-explorer-mcp-server",
  112. "run",
  113. "server.py"
  114. ],
  115. "env": {
  116. "AWS_ACCESS_KEY_ID": "YOUR_ACCESS_KEY_ID",
  117. "AWS_SECRET_ACCESS_KEY": "YOUR_SECRET_ACCESS_KEY",
  118. "AWS_REGION": "us-east-1",
  119. "BEDROCK_LOG_GROUP_NAME": "YOUR_CLOUDWATCH_BEDROCK_MODEL_INVOCATION_LOG_GROUP_NAME",
  120. "CROSS_ACCOUNT_ROLE_NAME": "ROLE_NAME_FOR_THE_ROLE_TO_ASSUME_IN_OTHER_ACCOUNTS",
  121. "MCP_TRANSPORT": "stdio"
  122. }
  123. }
  124. }
  125. }
  126. ```
  127. Make sure to replace the directory path with the actual path to your repository on your system.
  128. ### Remote setup
  129. 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](https://github.com/orgs/modelcontextprotocol/discussions/16) GitHub issue).
  130. #### Starting the Server (remote)
  131. 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](https://github.com/modelcontextprotocol/specification/discussions/102)), do not send or receive sensitive data over MCP**.
  132. Run the server using:
  133. ```
  134. export MCP_TRANSPORT=sse
  135. export BEDROCK_LOG_GROUP_NAME=YOUR_BEDROCK_CW_LOG_GROUP_NAME
  136. 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
  137. python server.py
  138. ```
  139. 1. The MCP server will start listening on TCP port 8000.
  140. 1. 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.
  141. >Also see section on running a ["secure" remote MCP server](#secure-remote-mcp-server) i.e. a server to which your MCP clients can connect over HTTPS.
  142. #### Testing with a CLI MCP client
  143. 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.
  144. ```{.bashrc}
  145. # set the hostname for your MCP server
  146. MCP_SERVER_HOSTNAME=YOUR_MCP_SERVER_EC2_HOSTNAME
  147. # or localhost if your MCP server is running locally
  148. # MCP_SERVER_HOSTNAME=localhost
  149. 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
  150. python mcp_sse_client.py --host $MCP_SERVER_HOSTNAME --aws-account-id $AWS_ACCOUNT_ID
  151. ```
  152. #### Testing with Chainlit app
  153. The `app.py` file in this repo provides a Chainlit app (chatbot) which creates a LangGraph agent that uses the [`LangChain MCP Adapter`](https://github.com/langchain-ai/langchain-mcp-adapters) 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 tools available to it via the remote MCP server to answer that question. We use Claude 3.5 Haiku model available via Amazon Bedrock to power this agent.
  154. Run the Chainlit app using:
  155. ```{.bashrc}
  156. chainlit run app.py --port 8080
  157. ```
  158. A browser window should open up on `localhost:8080` and you should be able to use the chatbot to get details about your AWS spend.
  159. ### Available Tools
  160. The server exposes the following tools that Claude can use:
  161. 1. **`get_ec2_spend_last_day()`**: Retrieves EC2 spending data for the previous day
  162. 1. **`get_detailed_breakdown_by_day(days=7)`**: Delivers a comprehensive analysis of costs by region, service, and instance type
  163. 1. **`get_bedrock_daily_usage_stats(days=7, region='us-east-1', log_group_name='BedrockModelInvocationLogGroup')`**: Delivers a per-day breakdown of model usage by region and users.
  164. 1. **`get_bedrock_hourly_usage_stats(days=7, region='us-east-1', log_group_name='BedrockModelInvocationLogGroup')`**: Delivers a per-day per-hour breakdown of model usage by region and users.
  165. ### Example Queries
  166. Once connected to Claude through an MCP-enabled interface, you can ask questions like:
  167. - "Help me understand my Bedrock spend over the last few weeks"
  168. - "What was my EC2 spend yesterday?"
  169. - "Show me my top 5 AWS services by cost for the last month"
  170. - "Analyze my spending by region for the past 14 days"
  171. - "Which instance types are costing me the most money?"
  172. - "Which services had the highest month-over-month cost increase?"
  173. ## Docker Support
  174. A Dockerfile is included for containerized deployment:
  175. ```
  176. docker build -t aws-cost-explorer-mcp .
  177. docker run -v ~/.aws:/root/.aws aws-cost-explorer-mcp
  178. ```
  179. ## Development
  180. ### Project Structure
  181. - `server.py`: Main server implementation with MCP tools
  182. - `pyproject.toml`: Project dependencies and metadata
  183. - `Dockerfile`: Container definition for deployments
  184. ### Adding New Cost Analysis Tools
  185. To extend the functionality:
  186. 1. Add new functions to `server.py`
  187. 2. Annotate them with `@mcp.tool()`
  188. 3. Implement the AWS Cost Explorer API calls
  189. 4. Format the results for easy readability
  190. ## Secure "remote" MCP server
  191. We can use [`nginx`](https://nginx.org/) as a reverse-proxy so that it can provide an HTTPS endpoint for connecting to the MCP server. Remote MCP clients can connect to `nginx` over HTTPS and then it can proxy traffic internally to `http://localhost:8000`. The following steps describe how to do this.
  192. 1. Enable access to TCP port 443 from the IP address of your MCP client (your laptop, or anywhere) in the inbound rules in the security group associated with your EC2 instance.
  193. 1. You would need to have an HTTPS certificate and private key to proceed. Let's say you use `your-mcp-server-domain-name.com` as the domain for your MCP server then you will need an SSL cert for `your-mcp-server-domain-name.com` and it will be accessible to MCP clients as `https://your-mcp-server-domain-name.com/sse`. _While you can use a self-signed cert but it would require disabling SSL verification on the MCP client, we DO NOT recommend you do that_. If you are hosting your MCP server on EC2 then you could generate an SSL cert using [no-ip](https://www.noip.com/) or [Let' Encrypt](https://letsencrypt.org/) or other similar services. Place the SSL cert and private key files in `/etc/ssl/certs` and `/etc/ssl/privatekey` folders respectively on your EC2 machine.
  194. 1. Install `nginx` on your EC2 machine using the following commands.
  195. ```{.bashrc}
  196. sudo apt-get install nginx
  197. sudo nginx -t
  198. sudo systemctl reload nginx
  199. ```
  200. 1. Get the hostname for your EC2 instance, this would be needed for configuring the `nginx` reverse proxy.
  201. ```{.bashrc}
  202. TOKEN=$(curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600") && curl -H "X-aws-ec2-metadata-token: $TOKEN" -s http://169.254.169.254/latest/meta-data/public-hostname
    • Dismissed after review: Fetches a raw IP-literal URL — ambiguous (could be legitimate internal tooling) but worth a second look
    • Line 283 on GitHub
  203. ```
  204. 1. Copy the following content into a new file `/etc/nginx/conf.d/ec2.conf`. Replace `YOUR_EC2_HOSTNAME`, `/etc/ssl/certs/cert.pem` and `/etc/ssl/privatekey/privkey.pem` with values appropriate for your setup.
  205. ```{.bashrc}
  206. server {
  207. listen 80;
  208. server_name YOUR_EC2_HOSTNAME;
  209. # Optional: Redirect HTTP to HTTPS
  210. return 301 https://$host$request_uri;
  211. }
  212. server {
  213. listen 443 ssl;
  214. server_name YOUR_EC2_HOSTNAME;
  215. # Self-signed certificate paths
  216. ssl_certificate /etc/ssl/certs/cert.pem;
  217. ssl_certificate_key /etc/ssl/privatekey/privkey.pem;
  218. # Optional: Good practice
  219. ssl_protocols TLSv1.2 TLSv1.3;
  220. ssl_ciphers HIGH:!aNULL:!MD5;
  221. location / {
  222. # Reverse proxy to your local app (e.g., port 8000)
  223. proxy_pass http://127.0.0.1:8000;
  224. proxy_http_version 1.1;
  225. proxy_set_header Host $host;
  226. proxy_set_header X-Real-IP $remote_addr;
  227. proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  228. }
  229. }
  230. ```
  231. 1. Restart `nginx`.
  232. ```{.bashrc}
  233. sudo systemctl start nginx
  234. ```
  235. 1. Start your MCP server as usual as described in the [remote setup](#remote-setup) section.
  236. 1. Your MCP server is now accessible over HTTPS as `https://your-mcp-server-domain-name.com/sse` to your MCP client.
  237. 1. On the client side now (say on your laptop or in your Agent) configure your MCP client to communicate to your MCP server as follows.
  238. ```{.bashrc}
  239. MCP_SERVER_HOSTNAME=YOUR_MCP_SERVER_DOMAIN_NAME
  240. 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
  241. python mcp_sse_client.py --host $MCP_SERVER_HOSTNAME --port 443 --aws-account-id $AWS_ACCOUNT_ID
  242. ```
  243. Similarly you could run the chainlit app to talk to remote MCP server over HTTPS.
  244. ```{.bashrc}
  245. export MCP_SERVER_URL=YOUR_MCP_SERVER_DOMAIN_NAME
  246. export MCP_SERVER_PORT=443
  247. chainlit run app.py --port 8080
  248. ```
  249. Similarly you could run the LangGraph Agent to talk to remote MCP server over HTTPS.
  250. ```{.bashrc}
  251. python langgraph_agent_mcp_sse_client.py --host $MCP_SERVER_HOSTNAME --port 443 --aws-account-id $AWS_ACCOUNT_ID
  252. ```
  253. ## License
  254. [MIT License](LICENSE)
  255. ## Acknowledgments
  256. - This tool uses Anthropic's MCP framework
  257. - Powered by AWS Cost Explorer API
  258. - Built with [FastMCP](https://github.com/jlowin/fastmcp) for server implementation
  259. - README was generated by providing a text dump of the repo via [GitIngest](https://gitingest.com/) to Claude

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.