# 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:**
   ```bash
   npm install
   npm run build
   ```

2. **Configure Claude Desktop:**
   ```bash
   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:

```json
{
  "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

| Tool | Description | Example Usage |
|------|-------------|---------------|
| `analyze_costs` | Analyze costs with filtering | "Show me EC2 costs for last month" |
| `compare_usage` | Compare periods | "Compare this month to last month" |
| `analyze_trends` | Trend analysis | "What are the cost trends for S3?" |
| `detect_anomalies` | Find anomalies | "Detect any cost anomalies" |
| `rank_costs` | Top cost drivers | "What are my biggest cost drivers?" |

## 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

```bash
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