AWS MCP

Interactúa con tu entorno de AWS usando lenguaje natural. Requiere credenciales locales de AWS.

Documentación

AWS Sage

Un servidor Model Context Protocol (MCP) de nivel de producción para AWS. Conecta asistentes de IA a tu infraestructura de AWS y adminístrala mediante conversación natural.

🚀 Funciona con cualquier cliente compatible con MCP — solo instala y configura.

Clientes Compatibles

Cliente	Estado	Notas
Claude Desktop	✅ Soporte completo	Recomendado
Claude Code	✅ Soporte completo	CLI e IDE
Cursor	✅ Soporte completo	MCP habilitado
Cline	✅ Soporte completo	Extensión de VS Code
Windsurf	✅ Soporte completo	MCP habilitado
Zed	✅ Soporte completo	MCP habilitado
VS Code + Copilot	⏳ Planificado	Vía extensión MCP

¿Por qué AWS Sage?

AWS Labs ofrece 15 servidores MCP separados para diferentes servicios. AWS Sage adopta un enfoque diferente:

Característica	AWS Labs MCP	AWS Sage
Arquitectura	15 servidores separados	1 servidor unificado
Herramientas	~45 herramientas entre servidores	30 herramientas inteligentes
Consultas entre servicios	No	Sí: descubre recursos en todos los servicios
Mapeo de dependencias	No	Sí: "¿de qué depende este recurso?"
Análisis de impacto	No	Sí: "¿qué se rompe si elimino esto?"
Investigación de incidentes	No	Sí: flujos de trabajo automatizados de resolución de problemas
Análisis de costos	Servidor separado	Integrado: recursos inactivos, ajuste de tamaño, proyecciones
Soporte LocalStack	No	Sí: desarrollo local sin fricciones
Multi-cuenta	No	Sí: entre cuentas mediante AssumeRole
Soporte Docker	Separado	Integrado con docker-compose
Sistema de seguridad	Básico	3 niveles con más de 70 operaciones bloqueadas
Lenguaje natural	Limitado	PLN completo con clasificación de intención

Características

Capacidades principales

Consultas en lenguaje natural: "Muéstrame instancias EC2 etiquetadas como producción"
Soporte multi-perfil: Cambia entre perfiles de AWS con soporte SSO
Auto-paginación: Nunca pierdas recursos por límites de paginación
Formato inteligente: Salida tabular para listas, JSON detallado para recursos individuales

Sistema de seguridad

Tres modos de seguridad protegen tu infraestructura:

Modo	Descripción	Operaciones permitidas
`READ_ONLY`	Predeterminado: solo exploración	list, describe, get
`STANDARD`	Operaciones normales	lectura + escritura (con confirmación)
`UNRESTRICTED`	Acceso completo	todas excepto lista de denegación

Siempre bloqueadas (más de 70 operaciones):

cloudtrail.delete_trail / stop_logging
iam.delete_account_password_policy
organizations.leave_organization
guardduty.delete_detector
kms.schedule_key_deletion
Y más de 65 operaciones críticas adicionales

Diferenciadores únicos

Descubrimiento de recursos entre servicios

Encuentra recursos en toda tu cuenta de AWS:

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

Mapeo de dependencias

Comprende las relaciones entre recursos:

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

Análisis de impacto

Conoce qué se rompe antes de eliminar:

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

Investigación de incidentes

Flujos de trabajo automatizados de resolución de problemas:

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

Análisis de costos

Encuentra ahorros y optimiza el gasto:

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

Integración con LocalStack

Desarrolla localmente sin tocar producción:

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

Soporte multi-cuenta

Trabaja entre cuentas de AWS:

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

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

¡Eso es todo! Claude Desktop ejecuta AWS Sage automáticamente cuando lo necesites.

Instalación

Requisitos previos

Python 3.11+
Credenciales de AWS configuradas (~/.aws/credentials o ~/.aws/config)
Cualquier cliente compatible con MCP (consulta Clientes Compatibles arriba)

Opción 1: Desde el código fuente

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

Opción 2: Directamente desde GitHub

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

Configuración del cliente

Primero, encuentra tu ruta de Python:

which python  # or: which python3

Claude Desktop

Ubicación del archivo de configuración:

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

Opción 1: Comando CLI

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

Opción 2: Configuración del proyecto (.mcp.json en la raíz del proyecto)

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

Opción 3: Configuración global (~/.claude.json)

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

Cursor

Archivo de configuración: ~/.cursor/mcp.json (global) o .cursor/mcp.json (proyecto)

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

Cline (Extensión de VS Code)

Archivo de configuración: Accede mediante la configuración de 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

Archivo de configuración:

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

Archivo de configuración: Configuración de Zed (settings.json)

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

VS Code (MCP nativo)

Archivo de configuración: .vscode/mcp.json (proyecto)

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

Instalación con Docker (todos los clientes)

Para mayor seguridad con aislamiento de contenedores:

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

Configuración de Docker (úsela en cualquier cliente anterior):

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

Referencia de herramientas (30 herramientas)

Gestión de credenciales

Herramienta	Descripción
`list_profiles`	Lista los perfiles de AWS disponibles
`select_profile`	Selecciona y autentica con un perfil
`get_account_info`	Muestra el ID de cuenta, región e identidad actuales

Controles de seguridad

Herramienta	Descripción
`set_safety_mode`	Cambia entre READ_ONLY, STANDARD, UNRESTRICTED

Operaciones de consulta (solo lectura)

Herramienta	Descripción
`aws_query`	Consultas de AWS en lenguaje natural
`validate_operation`	Verifica si una operación es válida sin ejecutarla

Operaciones de ejecución (requieren confirmación)

Herramienta	Descripción
`aws_execute`	Ejecuta operaciones de AWS validadas

Contexto y memoria

Herramienta	Descripción
`get_context`	Ver el contexto de la conversación y recursos recientes
`set_alias`	Crear atajos para recursos (p. ej., "prod-db")
`list_aliases`	Ver todos los alias definidos

Inteligencia entre servicios

Herramienta	Descripción
`discover_resources`	Encuentra recursos por etiquetas en todos los servicios
`map_dependencies`	Muestra de qué depende un recurso
`impact_analysis`	Predice qué se rompe si modificas/eliminas algo
`investigate_incident`	Flujos de trabajo automatizados de investigación de incidentes

Conocimiento de AWS (composición)

Herramienta	Descripción
`search_docs`	Busca en la documentación de AWS
`get_aws_knowledge`	Consulta la base de conocimiento integrada de AWS
`get_best_practices`	Obtén mejores prácticas específicas del servicio
`get_service_limits`	Muestra las cuotas de servicio predeterminadas

Análisis de costos

Herramienta	Descripción
`find_idle_resources`	Encuentra recursos EC2/RDS/EBS/EIP no utilizados
`get_rightsizing_recommendations`	Obtén sugerencias de ajuste de tamaño para EC2
`get_cost_breakdown`	Análisis de gasto por servicio/etiqueta
`project_costs`	Estima costos antes del despliegue

Gestión de entornos

Herramienta	Descripción
`list_environments`	Lista los entornos configurados (producción/localstack)
`switch_environment`	Cambia entre LocalStack y producción
`get_environment_info`	Detalles del entorno actual
`check_localstack`	Verifica la conectividad con LocalStack
`compare_environments`	Compara recursos entre entornos

Gestión multi-cuenta

Herramienta	Descripción
`assume_role`	Asume un rol en otra cuenta mediante STS
`list_accounts`	Muestra las cuentas configuradas
`switch_account`	Cambia el contexto de cuenta activo

Ejemplos 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álisis de costos

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

Desarrollo con LocalStack

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

Operaciones multi-cuenta

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

Descubrimiento entre servicios

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

Análisis de dependencias

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

Análisis de impacto

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

Investigación de incidentes

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

Arquitectura

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

Desarrollo (para contribuyentes)

Configuración

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

Ejecutar pruebas

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

Pruebas locales con LocalStack

Prueba contra LocalStack sin tocar AWS real:

# Start LocalStack
docker compose up -d localstack

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

Depurar el servidor directamente

Para desarrollo/depuración (no necesario para uso normal):

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

Variables de entorno

Variable	Descripción	Predeterminado
`AWS_PROFILE`	Perfil de AWS a usar	`default`
`AWS_DEFAULT_REGION`	Región de AWS predeterminada	`us-east-1`
`AWS_SAGE_SAFETY_MODE`	Modo de seguridad (read_only/standard/unrestricted)	`read_only`
`AWS_SAGE_LOCALSTACK_ENABLED`	Habilitar LocalStack por defecto	`false`
`AWS_SAGE_LOCALSTACK_HOST`	Host de LocalStack	`localhost`
`AWS_SAGE_LOCALSTACK_PORT`	Puerto de LocalStack	`4566`

Solución de problemas

Ver registros

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

Problemas comunes

"Perfil no encontrado"

Asegúrate de que las credenciales de AWS estén configuradas en ~/.aws/credentials o ~/.aws/config
Para perfiles SSO, ejecuta aws sso login --profile <name> primero

"Operación bloqueada"

Verifica el modo de seguridad actual con get_account_info
Usa set_safety_mode para cambiarlo si es necesario
Algunas operaciones están siempre bloqueadas (consulta la lista de denegación)

"Validación fallida"

El analizador valida las operaciones contra los modelos de botocore
Verifica la ortografía de los nombres de servicios/operaciones
Usa validate_operation para probar antes de ejecutar

"LocalStack no accesible"

Asegúrate de que LocalStack esté en ejecución: docker compose up -d localstack
Verifica el endpoint: curl http://localhost:4566/_localstack/health
Usa la herramienta check_localstack para diagnosticar

Hoja de ruta

v1.0.0 (Actual)

30 herramientas inteligentes en 10 categorías
Descubrimiento entre servicios, mapeo de dependencias, análisis de impacto
Analizador de optimización de costos
Integración con LocalStack
Soporte multi-cuenta
Contenedorización con Docker
Sistema de seguridad de 3 niveles con más de 70 operaciones bloqueadas

Futuro

Detección de desviación en CloudFormation
Definiciones de flujos de trabajo personalizados
Integración con el estado de Terraform
Escaneo de cumplimiento (benchmarks CIS)

Referencias

Especificación del Model Context Protocol - Anthropic, 2024
Ecosistema MCP - Más de 5,800 servidores, 97M descargas mensuales de SDK (2025)
Servidores MCP de AWS Labs - Implementaciones oficiales de MCP de AWS
Framework FastMCP - SDK de MCP para Python
LocalStack - Emulador local de la nube de AWS

Contribuciones

Consulta CONTRIBUTING.md para las pautas.

Licencia

Licencia MIT: consulta LICENSE para más detalles.

Contacto

Problemas en GitHub: arunsanna/aws-sage
Correo electrónico: arun.sanna@outlook.com
Sitio web: arunsanna.com