# AWS Billing MCP Server - Local Deployment Guide
## Prerequisites
1. **Node.js** (v18 or higher)
2. **npm** (comes with Node.js)
3. **Claude Desktop** application installed
## Quick Start
### 1. Build the Project
```bash
npm install
npm run build
```
### 2. Configure Claude Desktop
Copy the template and customize it for your setup:
Copy the template configuration and customize it:
```bash
cp claude-desktop-config-template.json claude-desktop-config.json
```
Then edit `claude-desktop-config.json` to replace the placeholder values:
Add the configuration to your Claude Desktop MCP settings file:
**Location of Claude Desktop config file:**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**Configuration to add:**
1. Replace `REPLACE_WITH_YOUR_PROJECT_PATH` with your actual project path (run `pwd` to get it)
2. Replace the AWS credential placeholders with your actual credentials (or leave as-is for mock data)
Example after customization:
```json
{
"mcpServers": {
"aws-billing-mcp-server": {
"command": "node",
"args": ["/your/actual/project/path/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"
}
}
}
}
```
### 3. Verify Build
Ensure the project is built correctly:
```bash
npm run build
```
This compiles TypeScript to JavaScript in the `dist/` directory.
### 4. Configure AWS Credentials (Optional)
The server works with mock data by default for testing. To use real AWS billing data, update the AWS credentials in 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-actual-access-key-id",
"AWS_SECRET_ACCESS_KEY": "your-actual-secret-access-key",
"AWS_REGION": "us-east-1"
}
}
}
}
```
**Security Note**: AWS credentials are stored in the Claude Desktop configuration file. Make sure this file has appropriate permissions and is not shared.
**Simplified Approach**: This version uses environment variables directly from Claude Desktop config - no database storage or encryption complexity. This is perfect for personal Claude Desktop use.
**AWS Permissions Required**: Your AWS credentials need the following permissions:
- `ce:GetCostAndUsage` - For Cost Explorer API access
- `ce:GetUsageReport` - For usage reports
- `ce:ListCostCategoryDefinitions` - For cost categories
- `organizations:ListAccounts` - For multi-account setups (optional)
You can create an IAM user with a policy like this:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ce:GetCostAndUsage",
"ce:GetUsageReport",
"ce:ListCostCategoryDefinitions",
"organizations:ListAccounts"
],
"Resource": "*"
}
]
}
```
### 5. Test Setup (Optional)
You can test the setup by running the unit tests:
```bash
npm test
```
This will verify that all components are working correctly.
### 6. Restart Claude Desktop
After adding the configuration, restart Claude Desktop for the changes to take effect.
## Available Tools
Once configured, you'll have access to these MCP tools in Claude:
1. **analyze_costs** - Analyze AWS costs with filtering options
2. **compare_usage** - Compare usage between two time periods
3. **analyze_trends** - Analyze cost trends over time
4. **detect_anomalies** - Detect cost anomalies in billing data
5. **rank_costs** - Rank top cost drivers by service, region, etc.
## Testing the Setup
1. Open Claude Desktop
2. Start a new conversation
3. Try asking: "Can you analyze my AWS costs for the last month?"
4. Claude should be able to use the MCP tools to respond
## Simplified for Claude Desktop
This version is optimized for Claude Desktop personal use:
- No HTTP health check endpoint (eliminates port conflicts)
- Direct MCP communication via stdio
- Simplified configuration
## Troubleshooting
### Server Not Starting
- Check that the path in the configuration is correct
- Ensure Node.js is installed and accessible
- Check Claude Desktop logs: `~/Library/Logs/Claude/mcp-server-aws-billing-mcp-server.log`
### No AWS Data
- The server works with mock data by default
- To use real AWS data, configure AWS credentials in the environment variables
- Ensure your AWS credentials have Cost Explorer permissions
### Permission Issues
- Make sure the `start-mcp-server.js` file is executable: `chmod +x start-mcp-server.js`
- Check file paths are correct and accessible
### Log File Issues
- The server automatically creates log directories
- Logs are stored in the project's `logs/` directory when possible
- Falls back to `~/.aws-billing-mcp-server/logs/` if project directory is not writable
### Common Errors
- **"ENOENT: no such file or directory, mkdir 'logs'"** - Fixed in latest version with automatic directory creation
- **"Module not found"** - Ensure you've run `npm run build` after any changes
- **"Permission denied"** - Check file permissions and paths in the configuration
- **"EADDRINUSE: address already in use"** - This error should no longer occur as the health check endpoint has been removed
- **"No billing data found"** - Run `node diagnose-aws-credentials.js` to check AWS credential setup and permissions
### AWS Credentials Issues
If you're getting "No billing data found" responses:
1. **Check AWS permissions**: Your credentials need Cost Explorer access
2. **Verify credentials**: Ensure AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are correct in Claude Desktop config
3. **Check billing data**: Ensure your AWS account has billing history in the requested date range
4. **Check logs**: Look at Claude Desktop MCP server logs for error details
## Development Mode
For development, you can run the server directly:
```bash
npm run dev
```
This will start the server with hot reloading for development.
## Configuration Options
Environment variables you can set:
- `AUTH_ENABLED`: Enable/disable Google SSO authentication (default: false)
- `LOG_LEVEL`: Logging level (debug, info, warn, error) (default: info)
- `AWS_ACCESS_KEY_ID`: AWS access key for real billing data
- `AWS_SECRET_ACCESS_KEY`: AWS secret key for real billing data
- `AWS_REGION`: AWS region (default: us-east-1)
## Security Notes
- Authentication is disabled by default for local development
- For production use, enable authentication and configure Google SSO
- AWS credentials are optional - the server works with mock data for testing
## Testing the MCP Server
You can test the MCP server functionality by:
1. **Running unit tests**: `npm test`
2. **Testing with Claude Desktop**: Ask Claude "Can you analyze my AWS costs for the last month?"
3. **Checking logs**: Monitor Claude Desktop MCP server logs for any issues
## Example Claude Desktop Configuration File
Here's a complete example of what your `claude_desktop_config.json` should look like:
```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-aws-access-key-id",
"AWS_SECRET_ACCESS_KEY": "your-aws-secret-access-key",
"AWS_REGION": "us-east-1"
}
}
}
}
```
## Verifying the Setup
1. **Check server startup**: Look at Claude Desktop logs for any startup errors
2. **Run unit tests**: `npm test` to verify components work correctly
3. **Test with Claude**: Ask Claude about AWS costs to verify MCP tools are available
## Available MCP Tools
The server provides these tools to Claude:
| Tool Name | Description | Parameters |
|-----------|-------------|------------|
| `analyze_costs` | Analyze AWS costs with filtering | accountId, services, regions, startDate, endDate |
| `compare_usage` | Compare usage between periods | currentPeriod, previousPeriod, accountId, services, regions |
| `analyze_trends` | Analyze cost trends over time | accountId, regions, startDate, endDate, service |
| `detect_anomalies` | Detect cost anomalies | accountId, services, regions, startDate, endDate |
| `rank_costs` | Rank top cost drivers | accountId, services, regions, startDate, endDate |
## Sample Claude Queries
Once configured, you can ask Claude questions like:
- "Analyze my AWS costs for the last month"
- "Compare my current month's usage to last month"
- "Show me the top cost drivers in my AWS account"
- "Detect any cost anomalies in my billing data"
- "What are the cost trends for EC2 services?"
