AWS Sage

A production-grade Model Context Protocol (MCP) server for AWS. Connect AI assistants to your AWS infrastructure and manage it through natural conversation.

🚀 Works with any MCP-compatible client - just install and configure.

Compatible Clients

Why AWS Sage?

AWS Labs offers 15 separate MCP servers for different services. AWS Sage takes a different approach:

Features

Core Capabilities

• Natural Language Queries: "Show me EC2 instances tagged production"
• Multi-Profile Support: Switch between AWS profiles with SSO support
• Auto-Pagination: Never miss resources due to pagination limits
• Smart Formatting: Tabular output for lists, detailed JSON for single resources

Safety System

Three safety modes protect your infrastructure:

Always Blocked (70+ operations):

• cloudtrail.delete_trail / stop_logging
• iam.delete_account_password_policy
• organizations.leave_organization
• guardduty.delete_detector
• kms.schedule_key_deletion
• And 65+ more critical operations

Unique Differentiators

Cross-Service Resource Discovery

Find resources across your entire AWS account:

"Find all resources tagged Environment=production"
"Discover resources with Name containing api"

Dependency Mapping

Understand resource relationships:

"What resources does my Lambda function depend on?"
"Map dependencies for my ECS service"

Impact Analysis

Know what breaks before you delete:

"What will break if I delete this security group?"
"Show impact of removing this IAM role"

Incident Investigation

Automated troubleshooting workflows:

"Investigate why my Lambda is failing"
"Debug high latency on my ALB"
"Analyze this security alert"

Cost Analysis

Find savings and optimize spending:

"Find idle resources in my account"
"Get rightsizing recommendations for EC2"
"Project costs for 3 t3.large instances"

LocalStack Integration

Develop locally without touching production:

"Switch to LocalStack environment"
"Compare S3 buckets between localstack and production"

Multi-Account Support

Work across AWS accounts:

"Assume role in account 123456789012"
"Switch to production account"

Quick Start

# 1. Clone and install
git clone https://github.com/arunsanna/aws-sage
cd aws-sage
pip install .

# 2. Add to Claude Desktop config (see Configuration below)
# 3. Restart Claude Desktop
# 4. Start chatting: "List my S3 buckets"

That's it! Claude Desktop automatically runs AWS Sage when needed.

Installation

Prerequisites

• Python 3.11+
• AWS credentials configured (~/.aws/credentials or ~/.aws/config)
• Any MCP-compatible client (see Compatible Clients above)

Option 1: From Source

git clone https://github.com/arunsanna/aws-sage
cd aws-sage
pip install .

Option 2: Direct from GitHub

pip install git+https://github.com/arunsanna/aws-sage.git

Client Configuration

First, find your Python path:

which python  # or: which python3

Claude Desktop

Config file location:

{
  "mcpServers": {
    "aws-sage": {
      "command": "/path/to/python3",
      "args": ["-m", "aws_sage.server"],
      "env": {
        "AWS_PROFILE": "default"
      }
    }
  }
}

Claude Code

Option 1: CLI command

claude mcp add aws-sage -s user -- python -m aws_sage.server

Option 2: Project config (.mcp.json in project root)

{
  "mcpServers": {
    "aws-sage": {
      "command": "python",
      "args": ["-m", "aws_sage.server"],
      "env": {
        "AWS_PROFILE": "default"
      }
    }
  }
}

Option 3: Global config (~/.claude.json)

{
  "mcpServers": {
    "aws-sage": {
      "command": "python",
      "args": ["-m", "aws_sage.server"],
      "env": {
        "AWS_PROFILE": "default"
      }
    }
  }
}

Cursor

Config file: ~/.cursor/mcp.json (global) or .cursor/mcp.json (project)

{
  "mcpServers": {
    "aws-sage": {
      "command": "python",
      "args": ["-m", "aws_sage.server"],
      "env": {
        "AWS_PROFILE": "default"
      }
    }
  }
}

Cline (VS Code Extension)

Config file: Access via Cline settings → "Configure MCP Servers" → cline_mcp_settings.json

{
  "mcpServers": {
    "aws-sage": {
      "command": "python",
      "args": ["-m", "aws_sage.server"],
      "env": {
        "AWS_PROFILE": "default"
      },
      "disabled": false
    }
  }
}

Windsurf

Config file:

{
  "mcpServers": {
    "aws-sage": {
      "command": "python",
      "args": ["-m", "aws_sage.server"],
      "env": {
        "AWS_PROFILE": "default"
      }
    }
  }
}

Zed

Config file: Zed Settings (settings.json)

{
  "context_servers": {
    "aws-sage": {
      "command": "python",
      "args": ["-m", "aws_sage.server"],
      "env": {
        "AWS_PROFILE": "default"
      }
    }
  }
}

VS Code (Native MCP)

Config file: .vscode/mcp.json (project)

{
  "servers": {
    "aws-sage": {
      "command": "python",
      "args": ["-m", "aws_sage.server"],
      "env": {
        "AWS_PROFILE": "default"
      }
    }
  }
}

Docker Installation (All Clients)

For enhanced security with container isolation:

git clone https://github.com/arunsanna/aws-sage
cd aws-sage
docker compose build aws-sage

Docker config (use in any client above):

macOS/Linux:

{
  "command": "docker",
  "args": [
    "run", "-i", "--rm",
    "-v", "${HOME}/.aws:/home/appuser/.aws:ro",
    "-e", "AWS_PROFILE=default",
    "aws-sage:latest"
  ]
}

Windows:

{
  "command": "docker",
  "args": [
    "run", "-i", "--rm",
    "-v", "%USERPROFILE%\\.aws:/home/appuser/.aws:ro",
    "-e", "AWS_PROFILE=default",
    "aws-sage:latest"
  ]
}

Tools Reference (30 Tools)

Credential Management

Safety Controls

Query Operations (Read-Only)

Execute Operations (Require Confirmation)

Context & Memory

Cross-Service Intelligence

AWS Knowledge (Composition)

Cost Analysis

Environment Management

Multi-Account Management

Usage Examples

Basic Queries

"List all S3 buckets"
"Show EC2 instances in us-west-2"
"Describe Lambda function payment-processor"
"Get IAM users with console access"

Cost Analysis

"Find idle resources in us-east-1"
"Get rightsizing recommendations for EC2"
"Show cost breakdown by service for last 30 days"
"Project costs for 2 t3.large and 100GB gp3 EBS"

LocalStack Development

"Switch to localstack"
"Create an S3 bucket in localstack"
"Compare DynamoDB tables between localstack and production"
"Check localstack connectivity"

Multi-Account Operations

"Assume role arn:aws:iam::123456789012:role/AdminRole"
"List all configured accounts"
"Switch to production account"

Cross-Service Discovery

"Find all resources tagged with Environment=production"
"Discover resources owned by team-platform"
"Show all resources in the payment-service stack"

Dependency Analysis

"What does my api-gateway Lambda depend on?"
"Map all dependencies for the checkout-service ECS task"
"Show resources connected to vpc-abc123"

Impact Analysis

"What breaks if I delete sg-abc123?"
"Impact of terminating this RDS instance"
"What depends on this KMS key?"

Incident Investigation

"Investigate Lambda failures for order-processor"
"Debug high latency: ALB arn:aws:elasticloadbalancing:..."
"Analyze security alert for instance i-abc123"

Architecture

aws-sage/
├── Dockerfile                  # Container support
├── docker-compose.yml          # LocalStack + MCP server
│
├── src/aws_sage/
│   ├── server.py              # FastMCP server (30 tools)
│   ├── config.py              # Configuration & safety modes
│   │
│   ├── core/
│   │   ├── session.py         # AWS session management
│   │   ├── context.py         # Conversation memory
│   │   ├── environment.py     # Environment configuration
│   │   ├── environment_manager.py  # LocalStack/production switching
│   │   ├── multi_account.py   # Cross-account management
│   │   └── exceptions.py      # Custom exceptions
│   │
│   ├── safety/
│   │   ├── classifier.py      # Operation classification
│   │   ├── validator.py       # Pre-execution validation
│   │   └── denylist.py        # Blocked operations (70+)
│   │
│   ├── parser/
│   │   ├── intent.py          # NLP intent classification
│   │   └── service_models.py  # Botocore integration
│   │
│   ├── execution/
│   │   ├── engine.py          # Execution orchestrator
│   │   └── pagination.py      # Auto-pagination
│   │
│   ├── composition/
│   │   ├── docs_proxy.py      # AWS documentation
│   │   └── knowledge_proxy.py # AWS knowledge base + live query
│   │
│   └── differentiators/
│       ├── discovery.py       # Cross-service discovery
│       ├── dependencies.py    # Dependency mapping
│       ├── workflows.py       # Incident investigation
│       ├── cost.py            # Cost analysis
│       └── compare.py         # Environment comparison
│
└── tests/
    ├── unit/                  # Unit tests (145 tests)
    └── integration/           # Integration tests

Development (For Contributors)

Setup

git clone https://github.com/arunsanna/aws-sage
cd aws-sage
pip install -e ".[dev]"

Run Tests

pytest                          # All tests
pytest --cov=aws_sage           # With coverage
pytest tests/unit/test_cost.py  # Specific module

Local Testing with LocalStack

Test against LocalStack without touching real AWS:

# Start LocalStack
docker compose up -d localstack

# In Claude Desktop, say:
# "Switch to localstack environment"
# "Create test bucket my-test-bucket"

Debug Server Directly

For development/debugging (not needed for normal use):

fastmcp dev src/aws_sage/server.py  # Interactive mode
python -m aws_sage.server           # Direct run

Environment Variables

Troubleshooting

View Logs

# Claude Desktop logs
tail -f ~/Library/Logs/Claude/mcp-server-aws-sage.log
tail -f ~/Library/Logs/Claude/mcp.log

Common Issues

"Profile not found"

• Ensure AWS credentials are configured in ~/.aws/credentials or ~/.aws/config
• For SSO profiles, run aws sso login --profile <name> first

"Operation blocked"

• Check current safety mode with get_account_info
• Use set_safety_mode to change if needed
• Some operations are always blocked (see denylist)

"Validation failed"

• The parser validates operations against botocore models
• Check spelling of service/operation names
• Use validate_operation to test before executing

"LocalStack not reachable"

• Ensure LocalStack is running: docker compose up -d localstack
• Check endpoint: curl http://localhost:4566/_localstack/health
• Use check_localstack tool to diagnose

Roadmap

v1.0.0 (Current)

• 30 intelligent tools across 10 categories
• Cross-service discovery, dependency mapping, impact analysis
• Cost optimization analyzer
• LocalStack integration
• Multi-account support
• Docker containerization
• 3-tier safety system with 70+ blocked operations

Future

• CloudFormation drift detection
• Custom workflow definitions
• Terraform state integration
• Compliance scanning (CIS benchmarks)

References

• Model Context Protocol Specification - Anthropic, 2024
• MCP Ecosystem - 5,800+ servers, 97M monthly SDK downloads (2025)
• AWS Labs MCP Servers - Official AWS MCP implementations
• FastMCP Framework - Python MCP SDK
• LocalStack - Local AWS cloud emulator

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Contact

• GitHub Issues: arunsanna/aws-sage
• Email: arun.sanna@outlook.com
• Website: arunsanna.com