# 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
