aws-cost-mcp

An MCP server that lets AI agents (Claude, Cursor, Copilot, any MCP client) answer questions about your AWS bill — with guardrails, caching and zero write access.

You: "Why did our AWS bill jump 40% last week?"
Agent → aws-cost-mcp.get_cost_breakdown(groupBy: SERVICE, granularity: DAILY)
Agent → aws-cost-mcp.get_anomalies(last: 14d)
Agent: "Most of the increase comes from NAT Gateway data transfer in us-east-1, starting Tuesday…"

Why

Cost questions are some of the most common — and most painful — questions an engineering team asks. The answer lives in Cost Explorer, behind several clicks, filters and tag conventions that only one person on the team understands.

This project exposes AWS Cost Explorer as a read-only, well-typed MCP server, so that any agent can investigate spend, explain variations and suggest savings, using the same data a FinOps engineer would.

It was built from real experience migrating a campaign platform to AWS and driving its infrastructure cost down — the questions this server answers are the ones I had to answer by hand.

Related MCP server: Cost Explorer MCP Server

Features

Resources

• aws-cost://summary/month-to-date — compact markdown summary the agent can load as context.

Prompts

• investigate-cost-spike — guided workflow: compare → break down → check anomalies → explain.

• monthly-finops-report — produces a report for leadership.

Design principles

• Read-only by construction. The server only calls ce:Get* APIs. A minimal IAM policy is provided below.

• Cheap to run. Cost Explorer charges per API request, so every response is cached (in-memory LRU, configurable TTL) and requests are deduplicated.

• Agent-friendly output. Responses are compact, sorted and truncated (top-N + "others") to save context tokens. Raw JSON is available with format: "json".

• Strict input validation. All tool inputs are validated with Zod; invalid ranges and granularities return actionable errors the agent can fix itself.

Quick start

1. Requirements

• Node.js ≥ 20

• AWS credentials with the policy below (profile, SSO or env vars)

• Cost Explorer enabled in the account

2. Use with Claude Desktop / Claude Code / Cursor

{
  "mcpServers": {
    "aws-cost": {
      "command": "npx",
      "args": ["-y", "aws-cost-mcp"],
      "env": {
        "AWS_PROFILE": "my-readonly-profile",
        "AWS_COST_MCP_CACHE_TTL": "900"
      }
    }
  }
}

3. Run locally (development)

git clone https://github.com/VictorCarvalho16/aws-cost-mcp
cd aws-cost-mcp
npm install
npm run dev            # stdio server with hot reload
npm run inspector      # opens the MCP Inspector against the local server

Minimal IAM policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ce:GetCostAndUsage",
        "ce:GetCostForecast",
        "ce:GetAnomalies",
        "ce:GetRightsizingRecommendation",
        "ce:GetTags"
      ],
      "Resource": "*"
    }
  ]
}

Configuration

Architecture

┌──────────────┐  stdio / Streamable HTTP  ┌──────────────────────────────┐
│  MCP client  │ ────────────────────────▶ │  aws-cost-mcp                │
│ (Claude etc.)│                           │  ├─ tools/   (Zod schemas)   │
└──────────────┘                           │  ├─ services/costExplorer.ts │
                                           │  ├─ cache/   (LRU + dedupe)  │
                                           │  └─ format/  (md tables)     │
                                           └──────────────┬───────────────┘
                                                          │ AWS SDK v3
                                                          ▼
                                                 AWS Cost Explorer API

src/
├── index.ts              # entrypoint, transport selection
├── server.ts             # McpServer registration (tools, resources, prompts)
├── tools/                # one file per tool: schema + handler
├── services/
│   └── cost-explorer.ts  # thin typed wrapper over @aws-sdk/client-cost-explorer
├── cache/
├── format/               # markdown/JSON formatters, top-N truncation
└── config.ts
test/
├── unit/                 # handlers with mocked SDK (aws-sdk-client-mock)
└── e2e/                  # spawns the server and talks MCP over stdio

Stack: TypeScript · @modelcontextprotocol/sdk · AWS SDK v3 · Zod · Vitest · tsup · GitHub Actions

Testing

npm test               # unit tests (no AWS needed — SDK is mocked)
npm run test:e2e       # starts the server and runs real MCP requests against fixtures
npm run lint && npm run typecheck

Roadmap

v0.1 — MVP

• Project scaffold (TypeScript, tsup, Vitest, ESLint, Prettier)

• get_cost_breakdown with Zod validation

• Markdown formatter with top-N truncation

• Unit tests with aws-sdk-client-mock

• CI on GitHub Actions (lint, typecheck, test)

v0.2 — Useful

• compare_periods, get_forecast, list_tag_values

• LRU cache + request dedupe

• investigate-cost-spike prompt

• Publish to npm, add to the MCP Registry

v0.3 — Production-grade

• get_anomalies, get_rightsizing

• Streamable HTTP transport (for remote/shared deployments)

• E2E tests over stdio

• Demo GIF in this README

• Blog post: "Giving an AI agent read-only access to your AWS bill"

Ideas

• Multi-account (Organizations) support

• Savings Plans / RI coverage tools

• Export a report as CSV resource

Security

• Never request write permissions — the server has no code path that mutates AWS resources.

• Logs go to stderr only (stdout is reserved for the MCP protocol).

• Credentials are resolved by the AWS SDK default chain and never logged or returned to the client.

Found a vulnerability? Please open a private security advisory instead of an issue.

Contributing

Issues and PRs are welcome. Run npm test before opening a PR and follow Conventional Commits.

License

MIT © Victor Hugo Araújo de Carvalho