AWS Billing MCP Server

A Model Context Protocol (MCP) server that provides AWS billing and cost analysis tools for Claude Desktop.

Features

• 🔍 Cost Analysis - Analyze AWS costs with flexible filtering
• 📊 Usage Comparison - Compare usage between different time periods
• 📈 Trend Analysis - Identify cost trends over time
• 🚨 Anomaly Detection - Detect unusual cost patterns
• 🏆 Cost Ranking - Identify top cost drivers by service, region, etc.

Quick Setup

1. Install dependencies and build:

   npm install
   npm run build
   

2. Configure Claude Desktop:

   cp claude-desktop-config-template.json claude-desktop-config.json
   # Edit claude-desktop-config.json with your project path and AWS credentials
   

3. Copy the generated configuration to Claude Desktop:

   • Open claude-desktop-config.json
   • Copy its contents to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
   • Restart Claude Desktop

4. Test it: Ask Claude: "Can you analyze my AWS costs for the last month?"

Configuration

Simplified Claude Desktop Setup

The server is designed for Claude Desktop personal use with direct environment variable access:

Mock Data (Default): Works out of the box - no AWS credentials needed for testing.

Real AWS Data: Add your credentials directly to the Claude Desktop configuration:

{
  "mcpServers": {
    "aws-billing-mcp-server": {
      "command": "node",
      "args": ["/path/to/your/project/start-mcp-server.js"],
      "env": {
        "AUTH_ENABLED": "false",
        "LOG_LEVEL": "info",
        "AWS_ACCESS_KEY_ID": "your-access-key-id",
        "AWS_SECRET_ACCESS_KEY": "your-secret-access-key",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

Key Benefits:

• ✅ No database credential storage - uses environment variables directly
• ✅ No encryption/decryption complexity
• ✅ Simple and secure for personal Claude Desktop use
• ✅ Automatic fallback to mock data if credentials not provided

Required AWS Permissions:

• ce:GetCostAndUsage
• ce:GetUsageReport
• ce:ListCostCategoryDefinitions

Available Tools

Testing

• Run unit tests: npm test
• Check Claude Desktop logs: Look for startup messages in Claude's MCP server logs
• Test with Claude: Ask "Can you analyze my AWS costs for the last month?"

Files

• src/ - TypeScript source code

• dist/ - Compiled JavaScript output

• data/ - SQLite database storage

• logs/ - Application logs

• start-mcp-server.js - Server startup script

• claude-desktop-config-template.json - Configuration template

• DEPLOYMENT.md - Detailed deployment guide

Architecture

• MCP Server - Handles Claude Desktop communication via stdio
• Billing Client - AWS Cost Explorer API integration (simplified for environment variables)
• Billing Analyzer - Cost analysis algorithms
• Auth Manager - Google SSO authentication (disabled by default for Claude Desktop)
• Database - SQLite for caching billing data only (no credential storage)

Development

npm run dev      # Development mode with hot reload
npm test         # Run test suite
npm run lint     # Code linting
npm run format   # Code formatting

Security

• Authentication disabled by default for local development
• AWS credentials stored in Claude Desktop configuration
• Supports Google SSO for production deployments
• All data cached locally in SQLite database

Support

For issues or questions:

1. Check the health endpoint: http://localhost:37291/health
2. Review logs in the console output
3. Test MCP protocol with node test-mcp-tools.js
4. See DEPLOYMENT.md for detailed troubleshooting