aws-cost-explorer-mcp-server

marcllort/aws-cost-explorer-mcp-server

3.1

If you are the rightful owner of aws-cost-explorer-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Autocost Controller is a multi-cloud cost analysis and optimization platform with MCP integration, providing powerful tools for AWS cost management and future support for GCP and Azure.

Tools
5
Resources
0
Prompts
0

Autocost Controller

Multi-cloud cost analysis and optimization platform with MCP (Model Context Protocol) integration.

Autocost Controller provides powerful cost analysis tools for AWS (with GCP and Azure coming soon) through a modern MCP server that integrates seamlessly with Claude Desktop and other MCP-compatible tools.

✨ Features

🔶 AWS Cost Explorer Integration

  • Cost Analysis: Detailed breakdowns by service, account, region, and time period
  • Dimension Discovery: Explore all available cost dimensions and filters
  • Tag Analysis: Analyze costs by custom tags and resource tagging strategies
  • Performance Metrics: EC2 performance insights with cost correlation
  • Optimization Recommendations: AI-powered cost optimization suggestions

🎯 Multi-Provider Architecture

  • Modular Design: Enable/disable providers based on your needs
  • Environment-Based Configuration: Control which providers are active
  • Unified Interface: Consistent tool naming and behavior across providers

🖥️ Claude Desktop Integration

  • Multiple Configurations: Separate endpoints for different providers
  • Environment Variables: Clean configuration without hardcoded values
  • Auto-Discovery: Automatically detects and configures Claude Desktop

🚀 Quick Start

Prerequisites

  • Python 3.8+
  • AWS CLI configured (for AWS features)
  • Claude Desktop (optional, for GUI integration)

Installation & Setup

Run the interactive setup script:

python start.py

This guided setup will:

  1. Install dependencies - All required Python packages
  2. Configure providers - AWS, GCP, Azure (as available)
  3. Set up authentication - Configurable auth methods (no hardcoded roles!)
  4. Configure Claude Desktop - Multiple endpoint configurations
  5. Test everything - Verify all components are working

The setup script is fully configurable and will ask you about:

  • Which cloud providers to enable
  • Your preferred AWS authentication method (profiles, roles, environment variables)
  • Whether to configure Claude Desktop integration
  • Whether to install Cursor integration

Manual Setup (Alternative)

If you prefer manual setup:

  1. Install dependencies:

    pip install -r requirements.txt

  2. Configure AWS credentials (choose one method):

    • AWS Profile: aws configure
    • Environment Variables: Set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
    • IAM Roles: Configure role assumption (SAML, cross-account, etc.)

  3. Save credentials for Claude Desktop:

    # After authenticating to AWS
python save_credentials.py

  4. Test the setup:

    python server_manual.py --test

🔧 Configuration

Environment Variables

Control provider configuration with environment variables:

# Enable specific providers (comma-separated)
export AUTOCOST_PROVIDERS="aws"           # AWS only
export AUTOCOST_PROVIDERS="aws,gcp"       # AWS + GCP (when available)

# Set endpoint identifier
export AUTOCOST_ENDPOINT="aws"            # or "unified", "gcp", etc.

# Enable/disable custom company-specific tools (default: true)
export AUTOCOST_ENABLE_CUSTOM_TOOLS="true"   # Enable advanced cost analysis tools
export AUTOCOST_ENABLE_CUSTOM_TOOLS="false"  # Disable custom tools (basic tools only)

Cursor Integration

Virtual Environment Setup

For Cursor integration to work properly, you need to set up a dedicated virtual environment. Follow these steps:

  1. Create and activate virtual environment:

    # Create a new virtual environment in the project directory
python -m venv venv

# Activate the virtual environment
# On macOS/Linux:
source venv/bin/activate
# On Windows:
.\venv\Scripts\activate

  2. Install dependencies in the virtual environment:

    # Make sure you're in the project root directory
pip install -e .  # Install the project in editable mode
pip install mcp   # Install the MCP package

  3. Configure Cursor to use the virtual environment: Make sure your ~/.cursor/mcp.json points to the virtual environment's Python:

    {
  "mcpServers": {
    "aws-cost-explorer": {
      "command": "/path/to/your/project/venv/bin/python",
      "args": ["/path/to/your/project/server_manual.py"],
      "env": {
        "AUTOCOST_PROVIDERS": "aws",
        "AUTOCOST_ENDPOINT": "manual",
        "AUTOCOST_ENABLE_CUSTOM_TOOLS": "true",
        "PYTHONPATH": "/path/to/your/project",
        "VIRTUAL_ENV": "/path/to/your/project/venv"
      },
      "cwd": "/path/to/your/project"
    }
  }
}

  4. Verify the setup:

    # Make sure you're in the virtual environment
source venv/bin/activate

# Test the server
python server_manual.py --test

  5. Important Notes:

    • The virtual environment must be created in the project directory
    • Always use absolute paths in the Cursor configuration
    • If you close Cursor, you may need to restart it to reconnect to the MCP server
    • If you see "0 tools enabled", make sure:
      • The virtual environment is active
      • All dependencies are installed in the virtual environment
      • The paths in mcp.json are correct and absolute
      • The server is running (check with --test flag)

The setup script automatically configures Cursor integration by:

  1. Creating settings.json: Enables MCP integration in Cursor

    • Location:
      • macOS: ~/Library/Application Support/Cursor/User/settings.json
      • Linux: ~/.config/cursor/User/settings.json
      • Windows: ~/AppData/Roaming/Cursor/User/settings.json

  2. Creating mcp.json: Configures MCP servers for each endpoint

    • Location:
      • macOS: ~/.cursor/mcp.json
      • Linux: ~/.config/cursor/mcp.json
      • Windows: ~/AppData/Roaming/Cursor/mcp.json
    • Contains:
      • Server configurations for each endpoint
      • Environment variables for provider selection
      • Command and arguments for server startup

Example mcp.json configuration:

{
  "autocost-aws": {
    "command": "/path/to/python",
    "args": ["/path/to/server_manual.py"],
    "env": {
      "AUTOCOST_ENDPOINT": "aws",
      "AUTOCOST_PROVIDERS": "aws"
    }
  },
  "autocost-unified": {
    "command": "/path/to/python",
    "args": ["/path/to/server_manual.py"],
    "env": {
      "AUTOCOST_ENDPOINT": "unified",
      "AUTOCOST_PROVIDERS": "aws,gcp"
    }
  }
}

After configuration:

  1. Restart Cursor to load the new MCP servers
  2. The Autocost Controller tools will be available in Cursor's AI features
  3. Each endpoint appears as a separate MCP server in Cursor

Claude Desktop Configurations

The setup script creates multiple configurations in Claude Desktop:

  • autocost-aws: AWS-only cost analysis
  • autocost-unified: Multi-provider analysis (when multiple providers enabled)

Each configuration is automatically optimized for its specific use case.

🔐 AWS Credential Management

The MCP server now includes automatic credential detection and multiple convenient ways to handle AWS credentials:

Automatic Credential Detection

When the server starts, it automatically:

  1. 🔍 Checks for working AWS credentials in the current environment
  2. 💾 Captures and saves them if found
  3. 🔄 Falls back to previously saved credentials if needed

Quick Setup Options

Option 1: Automatic with Current Session (Recommended)
# In your terminal where you've assumed the AWS role:
python start_with_current_creds.py

This will capture your current credentials and start the server automatically.

Option 2: Manual Credential Capture
# 1. In your terminal, assume your AWS role
assume billing_read_only.root.okta

# 2. Capture the session credentials
python save_current_session.py

# 3. Start the server (will auto-load the captured credentials)
python server_manual.py
Option 3: Use AWS Profiles
# Set your AWS profile
export AWS_PROFILE=your-profile-name
python server_manual.py

Troubleshooting Expired Credentials

If you see "ExpiredToken" errors:

  1. The server will automatically detect this
  2. Use the aws_test_connection tool to check status
  3. Use the aws_refresh_credentials tool to refresh from environment
  4. Or restart with fresh credentials using Option 1 above

New MCP Tools for Credential Management

  • aws_test_connection: Test current AWS connection and show identity
  • aws_refresh_credentials: Refresh credentials from environment variables
  • get_provider_status: Check status of all providers

🔑 Authentication

AWS Authentication Methods

Autocost Controller supports multiple AWS authentication methods:

1. AWS Profiles
aws configure --profile your-profile
export AWS_PROFILE=your-profile
2. Environment Variables
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
export AWS_SESSION_TOKEN=your-session-token  # if using temporary credentials
3. Role Assumption

For SAML, OIDC, or cross-account access:

# Example with saml2aws
saml2aws login --profile your-profile

# Example with AWS CLI role assumption
aws sts assume-role --role-arn arn:aws:iam::123456789012:role/YourRole --role-session-name session
4. Credential Saving for Claude Desktop

After authenticating with any method:

python save_credentials.py

This securely saves your current credentials for Claude Desktop to use.

Required AWS Permissions

Your AWS user/role needs these permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ce:GetCostAndUsage",
        "ce:GetDimensionValues",
        "ce:GetReservationCoverage",
        "ce:GetReservationPurchaseRecommendation",
        "ce:GetReservationUtilization",
        "ce:GetUsageReport",
        "cloudwatch:GetMetricStatistics",
        "cloudwatch:ListMetrics",
        "ec2:DescribeInstances",
        "ec2:DescribeInstanceTypes",
        "ec2:DescribeRegions",
        "ecs:ListClusters",
        "ecs:ListServices",
        "ecs:DescribeServices",
        "sts:GetCallerIdentity"
      ],
      "Resource": "*"
    }
  ]
}

🛠️ Usage

Direct MCP Server

Run the MCP server directly:

# Start server with environment-based configuration
python server_manual.py

# Test setup and credentials
python server_manual.py --test

# Show help
python server_manual.py --help

Claude Desktop Integration

After running python start.py and configuring Claude Desktop:

  1. Restart Claude Desktop
  2. Select your Autocost Controller endpoint from the tools menu
  3. Use natural language to analyze costs:
    • "Show me AWS costs for the last 7 days"
    • "Which services are costing the most this month?"
    • "Analyze costs by environment tag"
    • "Get performance insights for EC2 instances"
    • "Run a 28-day rolling average analysis"
    • "Analyze ECS costs with Container Insights impact"
    • "Detect tenant anomalies in the last week"

Environment Configuration

Set these environment variables to customize behavior:

# Enable/disable company-specific tools (default: true)
export AUTOCOST_ENABLE_CUSTOM_TOOLS=true

# Configure enabled providers (default: all available)
export AUTOCOST_PROVIDERS=aws,gcp,azure

# Set endpoint identifier for multi-endpoint setups
export AUTOCOST_ENDPOINT=production

AWS Profile Switching

New Feature: Switch between AWS profiles dynamically to access different permission levels.

Why Use Profile Switching?
  • EC2/ECS Insights: Performance insights require broader permissions (EC2:DescribeInstances, CloudWatch, etc.)
  • Cross-Account Analysis: Switch between profiles for different AWS accounts
  • Role-Based Access: Use different profiles for different permission levels
Quick Commands
# List available profiles
aws_profile_list()

# Switch to admin profile for enhanced insights
aws_profile_switch('admin-profile')

# Test current permissions
aws_test_permissions()

# Get EC2 performance insights (requires enhanced permissions)
aws_performance_ec2_insights(days=7)

# Switch back to limited profile
aws_profile_reset()
Typical Workflow
  1. Start with basic cost analysis (limited permissions)
  2. Check available profiles: aws_profile_list()
  3. Switch to admin profile: aws_profile_switch('admin-profile')
  4. Run enhanced analysis: aws_performance_ec2_insights()
  5. Switch back: aws_profile_reset()

See for detailed guide.

Available Tools

The MCP server provides these tools through Claude Desktop:

Core Tools
  • get_provider_status: Check status of all configured providers
  • ping_server: Test server connectivity and basic AWS access
AWS Profile Management
  • aws_profile_list: List all available AWS profiles
  • aws_profile_switch: Switch to a different AWS profile
  • aws_profile_info: Get detailed information about a profile
  • aws_profile_reset: Reset to default AWS credentials
  • aws_test_permissions: Test current profile's AWS service permissions
AWS Cost Explorer Tools
  • aws_cost_explorer_discover_dimensions: Discover available cost dimensions
  • aws_cost_explorer_analyze_by_service: Quick service cost breakdown
  • aws_cost_explorer_analyze_by_dimension: Analyze costs by any dimension
  • aws_cost_explorer_list_tag_keys: List available tag keys for analysis
  • aws_cost_explorer_analyze_by_custom_tag: Analyze costs by specific tags
  • aws_cost_explorer_analyze_by_name_tag: Analyze costs by Name tag values
  • aws_cost_explorer_analyze_specific_resource: Detailed analysis for a specific resource
AWS Performance Tools
  • aws_performance_ec2_insights: EC2 performance metrics with cost correlation (requires enhanced permissions)
  • get_ecs_performance_insights: ECS performance analysis (requires enhanced permissions)
  • get_cost_optimization_recommendations: AI-powered optimization suggestions
AWS Advanced Cost Analysis
  • aws_rolling_average_analysis: 28-day rolling average cost analysis with trend detection
  • aws_ecs_cost_deep_dive: Detailed ECS cost breakdown (Fargate vs EC2, Container Insights impact)
  • aws_spot_instance_cost_impact: Spot vs On-Demand analysis with volatility tracking
  • aws_savings_plan_utilization_analysis: Savings Plan efficiency and waste detection
  • aws_tenant_cost_analysis: Cost breakdown by organization/tenant with anomaly detection
  • aws_redshift_cost_analysis: Cluster-by-cluster Redshift cost analysis
  • aws_spot_capacity_impact_analysis: Spot capacity constraints and Savings Plan spillover analysis
  • aws_container_insights_cost_analysis: Container Insights monitoring costs and ROI analysis
  • aws_cross_service_impact_analysis: Track cascading cost impacts across services
  • aws_savings_plan_spillover_analysis: Analyze spillover when spot unavailability forces SP consumption
  • aws_instance_type_capacity_strategy: Instance type diversification and capacity planning recommendations
Company-Specific Tools (Optional - Enable via AUTOCOST_ENABLE_CUSTOM_TOOLS=true)
  • aws_tenant_anomaly_detector: Detect unusual tenant spending patterns with baseline comparison
  • aws_uat_environment_cost_monitor: Monitor UAT vs Production cost ratios and identify optimization opportunities

📁 Project Structure

autocost_controller/
├── core/                    # Core configuration and logging
├── providers/               # Cloud provider implementations
│   ├── aws/                # AWS provider
│   └── manager.py          # Provider management
├── tools/                   # MCP tool implementations
│   ├── __init__.py         # Core tools registration
│   ├── aws_tools.py        # AWS cost analysis tools
│   └── aws_performance.py  # AWS performance tools
├── server_manual.py         # MCP server (environment-aware)
├── save_credentials.py      # Credential management utility
├── start.py                # Interactive setup script
└── README.md               # This file

🔒 Security

  • Credentials are stored securely with restrictive file permissions (600)
  • No hardcoded secrets - all authentication is configurable
  • Environment-based configuration - no sensitive data in code
  • Read-only permissions - tools only read cost/performance data

🚨 Troubleshooting

AWS Authentication Issues

  1. Check credential status:

    python save_credentials.py --status

  2. Test AWS connectivity:

    aws sts get-caller-identity

  3. Verify saved credentials:

    python server_manual.py --test

Claude Desktop Issues

  1. Restart Claude Desktop after configuration changes

  2. Check configuration file location:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Linux: ~/.config/claude/claude_desktop_config.json
    • Windows: ~/AppData/Roaming/Claude/claude_desktop_config.json

  3. Verify MCP server logs in Claude Desktop's developer tools

Provider Status Issues

# Check which providers are ready
python server_manual.py --test

# Verify environment variables
echo $AUTOCOST_PROVIDERS
echo $AUTOCOST_ENDPOINT

🗺️ Roadmap

  • ✅ AWS Cost Explorer - Complete with advanced analytics
  • ✅ Multi-provider architecture - Extensible foundation
  • 🔄 GCP Cost Management - In development
  • 🔄 Azure Cost Management - In development
  • 🔄 Cross-cloud cost comparison - Planned
  • 🔄 Advanced optimization recommendations - AI-powered insights

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Test thoroughly
  5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

💡 Support

  • GitHub Issues: Report bugs and request features
  • Documentation: This README and inline code documentation
  • Setup Script: Run python start.py for guided setup assistance

Autocost Controller - Bringing powerful cloud cost analysis to your development workflow through Claude Desktop and MCP integration.