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

Client	Status	Notes
Claude Desktop	✅ Full Support	Recommended
Claude Code	✅ Full Support	CLI & IDE
Cursor	✅ Full Support	MCP enabled
Cline	✅ Full Support	VS Code extension
Windsurf	✅ Full Support	MCP enabled
Zed	✅ Full Support	MCP enabled
VS Code + Copilot	⏳ Planned	Via MCP extension

Why AWS Sage?

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

Feature	AWS Labs MCP	AWS Sage
Architecture	15 separate servers	1 unified server
Tools	~45 tools across servers	30 intelligent tools
Cross-Service Queries	No	Yes - discover resources across all services
Dependency Mapping	No	Yes - "what depends on this resource?"
Impact Analysis	No	Yes - "what breaks if I delete this?"
Incident Investigation	No	Yes - automated troubleshooting workflows
Cost Analysis	Separate server	Built-in - idle resources, rightsizing, projections
LocalStack Support	No	Yes - seamless local development
Multi-Account	No	Yes - cross-account via AssumeRole
Docker Support	Separate	Built-in with docker-compose
Safety System	Basic	3-tier with 70+ blocked operations
Natural Language	Limited	Full NLP with intent classification

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:

Mode	Description	Operations Allowed
`READ_ONLY`	Default - exploration only	list, describe, get
`STANDARD`	Normal operations	read + write (with confirmation)
`UNRESTRICTED`	Full access	all except denylist

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:

OS	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

{
  "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:

OS	Path
macOS	`~/.codeium/windsurf/mcp_config.json`
Windows	`%USERPROFILE%\.codeium\windsurf\mcp_config.json`

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

Tool	Description
`list_profiles`	List available AWS profiles
`select_profile`	Select and authenticate with a profile
`get_account_info`	Show current account ID, region, identity

Safety Controls

Tool	Description
`set_safety_mode`	Switch between READ_ONLY, STANDARD, UNRESTRICTED

Query Operations (Read-Only)

Tool	Description
`aws_query`	Natural language AWS queries
`validate_operation`	Check if an operation is valid without executing

Execute Operations (Require Confirmation)

Tool	Description
`aws_execute`	Execute validated AWS operations

Context & Memory

Tool	Description
`get_context`	View conversation context and recent resources
`set_alias`	Create shortcuts for resources (e.g., "prod-db")
`list_aliases`	View all defined aliases

Cross-Service Intelligence

Tool	Description
`discover_resources`	Find resources by tags across all services
`map_dependencies`	Show what a resource depends on
`impact_analysis`	Predict what breaks if you modify/delete something
`investigate_incident`	Automated incident investigation workflows

AWS Knowledge (Composition)

Tool	Description
`search_docs`	Search AWS documentation
`get_aws_knowledge`	Query built-in AWS knowledge base
`get_best_practices`	Get service-specific best practices
`get_service_limits`	Show default service quotas

Cost Analysis

Tool	Description
`find_idle_resources`	Find unused EC2/RDS/EBS/EIP resources
`get_rightsizing_recommendations`	Get EC2 right-sizing suggestions
`get_cost_breakdown`	Spending analysis by service/tag
`project_costs`	Estimate costs before deployment

Environment Management

Tool	Description
`list_environments`	List configured environments (production/localstack)
`switch_environment`	Switch between LocalStack and production
`get_environment_info`	Current environment details
`check_localstack`	Verify LocalStack connectivity
`compare_environments`	Diff resources between environments

Multi-Account Management

Tool	Description
`assume_role`	Assume role in another account via STS
`list_accounts`	Show configured accounts
`switch_account`	Change active account context

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

Variable	Description	Default
`AWS_PROFILE`	AWS profile to use	`default`
`AWS_DEFAULT_REGION`	Default AWS region	`us-east-1`
`AWS_SAGE_SAFETY_MODE`	Safety mode (read_only/standard/unrestricted)	`read_only`
`AWS_SAGE_LOCALSTACK_ENABLED`	Enable LocalStack by default	`false`
`AWS_SAGE_LOCALSTACK_HOST`	LocalStack host	`localhost`
`AWS_SAGE_LOCALSTACK_PORT`	LocalStack port	`4566`

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

Name		Name	Last commit message	Last commit date
Latest commit History 23 Commits
docs		docs
src/aws_sage		src/aws_sage
tests		tests
.DS_Store		.DS_Store
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
server.json		server.json

Folders and files

Latest commit

History

Repository files navigation

AWS Sage

Compatible Clients

Why AWS Sage?

Features

Core Capabilities

Safety System

Unique Differentiators

Cross-Service Resource Discovery

Dependency Mapping

Impact Analysis

Incident Investigation

Cost Analysis

LocalStack Integration

Multi-Account Support

Quick Start

Installation

Prerequisites

Option 1: From Source

Option 2: Direct from GitHub

Client Configuration

Claude Desktop

Claude Code

Cursor

Cline (VS Code Extension)

Windsurf

Zed

VS Code (Native MCP)

Docker Installation (All Clients)

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

Cost Analysis

LocalStack Development

Multi-Account Operations

Cross-Service Discovery

Dependency Analysis

Impact Analysis

Incident Investigation

Architecture

Development (For Contributors)

Setup

Run Tests

Local Testing with LocalStack

Debug Server Directly

Environment Variables

Troubleshooting

View Logs

Common Issues

Roadmap

References

Contributing

License

Contact

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Contributors

Uh oh!

Packages