AWS MCP

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

AWS Labs offers15 separate MCP serversfor different services. AWS Sage takes a different approach:

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

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

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

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

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

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

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

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

- Python 3.11+
- AWS credentials configured (~/.aws/credentialsor~/.aws/config)
- Any MCP-compatible client (seeCompatible Clientsabove)

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

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

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

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

Option 2: Project config(.mcp.jsonin 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" } } } }

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

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 } } }

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

Config file:Zed Settings (settings.json)

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

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

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):

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

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

Execute Operations (Require Confirmation)

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

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

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

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

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

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

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

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

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

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

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

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"

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

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

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

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

- Check current safety mode withget_account_info
- Useset_safety_modeto change if needed
- Some operations are always blocked (see denylist)

- The parser validates operations against botocore models
- Check spelling of service/operation names
- Usevalidate_operationto test before executing

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

- 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

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

- 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

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

Get prescriptive CDK advice, explain CDK Nag rules, check suppressions, generate Bedrock Agent schemas, and discover AWS Solutions Constructs patterns.