AWS MCP

Interaja com seu ambiente AWS usando linguagem natural. Requer credenciais AWS locais.

Documentação

AWS Sage

Um servidor Model Context Protocol (MCP) de nível de produção para AWS. Conecte assistentes de IA à sua infraestrutura AWS e gerencie-a por meio de conversa natural.

🚀 Funciona com qualquer cliente compatível com MCP - basta instalar e configurar.

Clientes Compatíveis

Cliente	Status	Notas
Claude Desktop	✅ Suporte completo	Recomendado
Claude Code	✅ Suporte completo	CLI e IDE
Cursor	✅ Suporte completo	MCP habilitado
Cline	✅ Suporte completo	Extensão do VS Code
Windsurf	✅ Suporte completo	MCP habilitado
Zed	✅ Suporte completo	MCP habilitado
VS Code + Copilot	⏳ Planejado	Via extensão MCP

Por que AWS Sage?

A AWS Labs oferece 15 servidores MCP separados para diferentes serviços. O AWS Sage adota uma abordagem diferente:

Recurso	AWS Labs MCP	AWS Sage
Arquitetura	15 servidores separados	1 servidor unificado
Ferramentas	~45 ferramentas entre servidores	30 ferramentas inteligentes
Consultas entre serviços	Não	Sim - descubra recursos em todos os serviços
Mapeamento de dependências	Não	Sim - "do que esse recurso depende?"
Análise de impacto	Não	Sim - "o que quebra se eu excluir isso?"
Investigação de incidentes	Não	Sim - fluxos de trabalho automatizados de solução de problemas
Análise de custos	Servidor separado	Integrada - recursos ociosos, dimensionamento correto, projeções
Suporte a LocalStack	Não	Sim - desenvolvimento local sem interrupções
Multi-conta	Não	Sim - entre contas via AssumeRole
Suporte a Docker	Separado	Integrado com docker-compose
Sistema de segurança	Básico	3 níveis com mais de 70 operações bloqueadas
Linguagem natural	Limitado	NLP completo com classificação de intenção

Recursos

Capacidades Principais

Consultas em linguagem natural: "Mostre-me instâncias EC2 marcadas como produção"
Suporte a múltiplos perfis: Alterne entre perfis AWS com suporte a SSO
Paginação automática: Nunca perca recursos devido a limites de paginação
Formatação inteligente: Saída tabular para listas, JSON detalhado para recursos individuais

Sistema de Segurança

Três modos de segurança protegem sua infraestrutura:

Modo	Descrição	Operações Permitidas
`READ_ONLY`	Padrão - apenas exploração	listar, descrever, obter
`STANDARD`	Operações normais	leitura + escrita (com confirmação)
`UNRESTRICTED`	Acesso total	tudo exceto lista de bloqueio

Sempre bloqueado (mais de 70 operações):

cloudtrail.delete_trail / stop_logging
iam.delete_account_password_policy
organizations.leave_organization
guardduty.delete_detector
kms.schedule_key_deletion
E mais de 65 operações críticas adicionais

Diferenciais Únicos

Descoberta de Recursos entre Serviços

Encontre recursos em toda a sua conta AWS:

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

Mapeamento de Dependências

Entenda as relações entre recursos:

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

Análise de Impacto

Saiba o que quebra antes de excluir:

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

Investigação de Incidentes

Fluxos de trabalho automatizados de solução de problemas:

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

Análise de Custos

Encontre economias e otimize gastos:

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

Integração com LocalStack

Desenvolva localmente sem tocar na produção:

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

Suporte a Múltiplas Contas

Trabalhe em várias contas AWS:

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

Início Rápido

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

É isso! O Claude Desktop executa automaticamente o AWS Sage quando necessário.

Instalação

Pré-requisitos

Python 3.11+
Credenciais AWS configuradas (~/.aws/credentials ou ~/.aws/config)
Qualquer cliente compatível com MCP (veja Clientes Compatíveis acima)

Opção 1: A partir do código-fonte

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

Opção 2: Direto do GitHub

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

Configuração do Cliente

Primeiro, encontre o caminho do seu Python:

which python  # or: which python3

Claude Desktop

Local do arquivo de configuração:

SO	Caminho
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

Opção 1: comando CLI

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

Opção 2: configuração do projeto (.mcp.json na raiz do projeto)

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

Opção 3: configuração global (~/.claude.json)

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

Cursor

Arquivo de configuração: ~/.cursor/mcp.json (global) ou .cursor/mcp.json (projeto)

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

Cline (Extensão do VS Code)

Arquivo de configuração: Acesse pelas configurações do Cline → "Configure MCP Servers" → cline_mcp_settings.json

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

Windsurf

Arquivo de configuração:

SO	Caminho
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

Arquivo de configuração: Configurações do Zed (settings.json)

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

VS Code (MCP nativo)

Arquivo de configuração: .vscode/mcp.json (projeto)

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

Instalação via Docker (todos os clientes)

Para segurança aprimorada com isolamento de contêiner:

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

Configuração Docker (use em qualquer cliente acima):

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

Referência de Ferramentas (30 Ferramentas)

Gerenciamento de Credenciais

Ferramenta	Descrição
`list_profiles`	Listar perfis AWS disponíveis
`select_profile`	Selecionar e autenticar com um perfil
`get_account_info`	Mostrar ID da conta atual, região, identidade

Controles de Segurança

Ferramenta	Descrição
`set_safety_mode`	Alternar entre READ_ONLY, STANDARD, UNRESTRICTED

Operações de Consulta (Somente Leitura)

Ferramenta	Descrição
`aws_query`	Consultas AWS em linguagem natural
`validate_operation`	Verificar se uma operação é válida sem executá-la

Operações de Execução (Exigem Confirmação)

Ferramenta	Descrição
`aws_execute`	Executar operações AWS validadas

Contexto e Memória

Ferramenta	Descrição
`get_context`	Visualizar contexto da conversa e recursos recentes
`set_alias`	Criar atalhos para recursos (ex.: "prod-db")
`list_aliases`	Visualizar todos os aliases definidos

Inteligência entre Serviços

Ferramenta	Descrição
`discover_resources`	Encontrar recursos por tags em todos os serviços
`map_dependencies`	Mostrar do que um recurso depende
`impact_analysis`	Prever o que quebra se você modificar/excluir algo
`investigate_incident`	Fluxos de trabalho automatizados de investigação de incidentes

Conhecimento AWS (Composição)

Ferramenta	Descrição
`search_docs`	Pesquisar documentação AWS
`get_aws_knowledge`	Consultar base de conhecimento AWS integrada
`get_best_practices`	Obter melhores práticas específicas do serviço
`get_service_limits`	Mostrar cotas padrão do serviço

Análise de Custos

Ferramenta	Descrição
`find_idle_resources`	Encontrar recursos EC2/RDS/EBS/EIP não utilizados
`get_rightsizing_recommendations`	Obter sugestões de dimensionamento correto do EC2
`get_cost_breakdown`	Análise de gastos por serviço/tag
`project_costs`	Estimar custos antes da implantação

Gerenciamento de Ambiente

Ferramenta	Descrição
`list_environments`	Listar ambientes configurados (produção/localstack)
`switch_environment`	Alternar entre LocalStack e produção
`get_environment_info`	Detalhes do ambiente atual
`check_localstack`	Verificar conectividade com LocalStack
`compare_environments`	Diferenciar recursos entre ambientes

Gerenciamento de Múltiplas Contas

Ferramenta	Descrição
`assume_role`	Assumir função em outra conta via STS
`list_accounts`	Mostrar contas configuradas
`switch_account`	Alterar contexto da conta ativa

Exemplos de Uso

Consultas Básicas

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

Análise de Custos

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

Desenvolvimento com LocalStack

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

Operações com Múltiplas Contas

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

Descoberta entre Serviços

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

Análise de Dependências

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

Análise de Impacto

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

Investigação de Incidentes

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

Arquitetura

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

Desenvolvimento (Para Contribuidores)

Configuração

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

Executar Testes

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

Testes Locais com LocalStack

Teste contra LocalStack sem tocar na AWS real:

# Start LocalStack
docker compose up -d localstack

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

Depurar Servidor Diretamente

Para desenvolvimento/depuração (não necessário para uso normal):

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

Variáveis de Ambiente

Variável	Descrição	Padrão
`AWS_PROFILE`	Perfil AWS a usar	`default`
`AWS_DEFAULT_REGION`	Região AWS padrão	`us-east-1`
`AWS_SAGE_SAFETY_MODE`	Modo de segurança (read_only/standard/unrestricted)	`read_only`
`AWS_SAGE_LOCALSTACK_ENABLED`	Habilitar LocalStack por padrão	`false`
`AWS_SAGE_LOCALSTACK_HOST`	Host do LocalStack	`localhost`
`AWS_SAGE_LOCALSTACK_PORT`	Porta do LocalStack	`4566`

Solução de Problemas

Ver Logs

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

Problemas Comuns

"Perfil não encontrado"

Garanta que as credenciais AWS estejam configuradas em ~/.aws/credentials ou ~/.aws/config
Para perfis SSO, execute aws sso login --profile <name> primeiro

"Operação bloqueada"

Verifique o modo de segurança atual com get_account_info
Use set_safety_mode para alterar se necessário
Algumas operações são sempre bloqueadas (veja a lista de bloqueio)

"Falha na validação"

O analisador valida operações contra modelos botocore
Verifique a grafia dos nomes de serviço/operação
Use validate_operation para testar antes de executar

"LocalStack inacessível"

Garanta que o LocalStack esteja em execução: docker compose up -d localstack
Verifique o endpoint: curl http://localhost:4566/_localstack/health
Use a ferramenta check_localstack para diagnosticar

Roteiro

v1.0.0 (Atual)

30 ferramentas inteligentes em 10 categorias
Descoberta entre serviços, mapeamento de dependências, análise de impacto
Analisador de otimização de custos
Integração com LocalStack
Suporte a múltiplas contas
Containerização Docker
Sistema de segurança em 3 níveis com mais de 70 operações bloqueadas

Futuro

Detecção de desvio do CloudFormation
Definições de fluxo de trabalho personalizadas
Integração com estado do Terraform
Verificação de conformidade (benchmarks CIS)

Referências

Model Context Protocol Specification - Anthropic, 2024
MCP Ecosystem - mais de 5.800 servidores, 97 milhões de downloads mensais do SDK (2025)
AWS Labs MCP Servers - Implementações oficiais de MCP da AWS
FastMCP Framework - Python MCP SDK
LocalStack - Emulador de nuvem AWS local

AWS MCP

Documentação

AWS Sage

Clientes Compatíveis

Por que AWS Sage?

Recursos

Capacidades Principais

Sistema de Segurança

Diferenciais Únicos

Descoberta de Recursos entre Serviços

Mapeamento de Dependências

Análise de Impacto

Investigação de Incidentes

Análise de Custos

Integração com LocalStack

Suporte a Múltiplas Contas

Início Rápido

Instalação

Pré-requisitos

Opção 1: A partir do código-fonte

Opção 2: Direto do GitHub

Configuração do Cliente

Claude Desktop

Claude Code

Cursor

Cline (Extensão do VS Code)

Windsurf

Zed

VS Code (MCP nativo)

Instalação via Docker (todos os clientes)

Referência de Ferramentas (30 Ferramentas)

Gerenciamento de Credenciais

Controles de Segurança

Operações de Consulta (Somente Leitura)

Operações de Execução (Exigem Confirmação)

Contexto e Memória

Inteligência entre Serviços

Conhecimento AWS (Composição)

Análise de Custos

Gerenciamento de Ambiente

Gerenciamento de Múltiplas Contas

Exemplos de Uso

Consultas Básicas

Análise de Custos

Desenvolvimento com LocalStack

Operações com Múltiplas Contas

Descoberta entre Serviços

Análise de Dependências

Análise de Impacto

Investigação de Incidentes

Arquitetura

Desenvolvimento (Para Contribuidores)

Configuração

Executar Testes

Testes Locais com LocalStack

Depurar Servidor Diretamente

Variáveis de Ambiente

Solução de Problemas

Ver Logs

Problemas Comuns

Roteiro

Referências

Contribuindo

Licença

Contato