How aarora79/aws-cost-explorer-mcp-server works
Project Type and Purpose
• This is an open‑source Python MCP (Model Control Protocol) server + client toolchain that exposes AWS Cost Explorer and Amazon Bedrock model invocation logs through Anthropic’s MCP framework.
• It provides both a server component (server.py) implementing a set of MCP‑annotated “tools” (AWS spend queries), and multiple clients: a CLI SSE client (mcp_sse_client.py), a Chainlit-based chatbot (app.py), and a LangGraph Agent client (langgraph_agent_mcp_sse_client.py).
• The purpose is to let users (via Claude Desktop or custom agents) query AWS spend and usage data in natural language.
File Structure Analysis
• Top‑level artifacts:
• server.py – the MCP server entrypoint, registers AWS Cost Explorer and CloudWatch query tools.
• app.py – a Chainlit app that spins up a LangGraph Agent using the MCP server’s tools.
• mcp_sse_client.py & langgraph_agent_mcp_sse_client.py – example client scripts using SSE transport.
• Dockerfile & pyproject.toml – for containerized deployment and dependency management.
• chainlit.md – documentation for the Chainlit app.
• No deep subdirectories—this is a single‐service codebase with multiple client scripts.
• Configuration/environment driven via ENV vars: AWS credentials, MCP_TRANSPORT (stdio vs sse), SSE host/port, Bedrock log group, cross‐account role.
README Insights
• Two transport modes: stdio for local, SSE (HTTP port 8000 or HTTPS via nginx reverse‐proxy) for remote.
• Chainlit app and Docker/UV deployment paths are documented.
Components & Interactions
a. Main Components:
• User Layer:
• Human user interacting via Claude Desktop, Chainlit web UI, or custom CLI.
• Client Layer:
• MCP Client (embedded in Claude Desktop or LangGraph Agent).
• CLI SSE client scripts (mcp_sse_client.py, langgraph_agent_mcp_sse_client.py).
• Chainlit Agent (app.py).
• Transport Layer:
• stdio (local)
• SSE (HTTP/S)
• Optional HTTPS reverse proxy (nginx) in remote setup.
• Server Layer:
• MCP Server (server.py, built on FastMCP) exposing tools:
– get_ec2_spend_last_day()
– get_detailed_breakdown_by_day()
– get_bedrock_daily_usage_stats()
– get_bedrock_hourly_usage_stats()
• Runs in Python 3.12 environment, optionally containerized via Docker or launched with UV.
• AWS Services:
• AWS Cost Explorer API
• AWS CloudWatch Logs (Bedrock invocation logs)
• IAM roles & cross‐account role assumption (via CROSS_ACCOUNT_ROLE_NAME)
b. Relationships & Data Flows:
• User → Client UI (Claude Desktop or web UI) → MCP Client module
• MCP Server → AWS Cost Explorer API (JSON over HTTPS)
• MCP Server → AWS CloudWatch Logs API (JSON over HTTPS)
• Server → (optional) nginx reverse proxy for HTTPS termination → Server
c. Architectural Patterns & Principles:
• RPC Microservice: Loose coupling between clients and server via JSON‑RPC 2.0 (MCP).
• Transport Abstraction: Switchable transports (stdio vs SSE vs HTTPS).
• Extensibility: New AWS query tools are simply annotated functions in server.py.
• Infrastructure as Code: Dockerfile + UV to standardize deployments.
• Security Boundary: AWS credentials and cross‐account roles separated at the server, no credentials in clients.
d. Key Technologies & Libraries:
• Python 3.12
• FastMCP (MCP server framework)
• Anthropic MCP protocol
• Docker & UV (for packaging/running)
• Chainlit & LangChain MCP Adapter (for chat UI)
• AWS SDK (boto3) under the hood in server
• nginx (optional) for HTTPS reverse proxy
Detail Level
• Don’t just show “Client → Server”; break out each transport mode.
• Environment variables feeding into the server (AWS creds, BEDROCK_LOG_GROUP_NAME, CROSS_ACCOUNT_ROLE_NAME, MCP_TRANSPORT).
• If desired, annotate the Docker/container boundary and the UV runtime.