README.md
A unified MCP server for AWS that enables natural language infrastructure management
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_loggingiam.delete_account_password_policyorganizations.leave_organizationguardduty.delete_detectorkms.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/credentialsor~/.aws/config) - Any MCP-compatible client (see Compatible Clients above)
Tools (5)
list_resourcesList AWS resources across services with filtering and pagination support.describe_resourceGet detailed information about a specific AWS resource.map_dependenciesMap dependencies for a specific AWS resource.analyze_impactAnalyze the impact of deleting a specific AWS resource.investigate_incidentRun automated troubleshooting workflows for AWS services.Environment Variables
AWS_PROFILEThe AWS profile to use for authentication.AWS_REGIONThe default AWS region to operate in.Configuration
claude_desktop_config.json
{"mcpServers": {"aws-sage": {"command": "python", "args": ["path/to/aws-sage/main.py"]}}}Try it
→Show me all EC2 instances tagged with Environment=production.
→What resources does my Lambda function depend on?
→What will break if I delete this security group?
→Investigate why my Lambda function is failing.
→Find idle resources in my account to help reduce costs.