MCP AWS Monitor

Servidor MCP para monitoreo de infraestructura AWS de Logispot.

Estructura del proyecto

mcp-aws-monitor/
├── .env                ← AWS 키 + Google OAuth 키 (git 미추적)
├── .env.example        ← .env 템플릿
├── .gitignore
├── pyproject.toml      ← 패키지 정의 (mcp, boto3, httpx, uvicorn 등)
├── README.md
└── src/
    ├── __init__.py
    ├── server.py       ← MCP 서버 진입점 (stdio / HTTP 모드)
    ├── google_oauth.py ← Google OAuth Provider (HTTP 모드용)
    ├── aws_client.py   ← boto3 클라이언트 팩토리 (lru_cache)
    ├── cloudwatch.py   ← CloudWatch 도구 4개
    ├── sqs.py          ← SQS 도구 3개
    ├── rds.py          ← RDS 도구 3개
    ├── s3.py           ← S3 도구 4개
    ├── ec2.py          ← EC2/ECS/AutoScaling 도구 5개
    ├── sns.py          ← SNS 도구 2개
    └── lambda_tools.py ← Lambda 도구 3개

Related MCP server: AWS SSO MCP Server

Métodos de integración

Se puede integrar con Claude Code de dos maneras.

Método 1: stdio (solo local)

Claude Code ejecuta el servidor MCP directamente como un proceso hijo. Solo se puede usar en la misma máquina y no requiere autenticación adicional.

Claude Code --stdio--> MCP 서버 (자식 프로세스)

Método de ejecución:

1. Cambiar la configuración de Claude Code a stdio (ver más abajo)

2. Se ejecuta automáticamente al iniciar Claude Code (no es necesario iniciar el servidor por separado)

Configuración de Claude Code (~/.claude.json o ~/.claude/.mcp.json):

{
  "mcpServers": {
    "aws-monitor": {
      "command": "/path/to/mcp-aws-monitor/.venv/bin/python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/mcp-aws-monitor"
    }
  }
}

CLI de registro:

claude mcp add aws-monitor -s user -- /path/to/mcp-aws-monitor/.venv/bin/python -m src.server

Método 2: HTTP + Google OAuth (remoto/multiusuario)

Ejecuta el servidor MCP como un servidor HTTP independiente y autentica con Google OAuth. Si se despliega el servidor en EC2, los miembros del equipo pueden compartirlo.

Claude Code --HTTP--> MCP 서버 (:8000)
                        ↓ (인증 필요)
                      브라우저 → Google 로그인
                        ↓ (로그인 완료)
                      /google/callback → MCP 토큰 발급
                        ↓
                      Claude Code가 토큰으로 MCP 도구 사용

Preparación previa:

1. Crear un cliente OAuth en Google Cloud Console

   • API y servicios → Pantalla de consentimiento OAuth → Tipo de usuario: Interno (solo permite la organización de Workspace)

   • Credenciales → ID de cliente OAuth → Aplicación web

   • URI de redirección autorizado: http://{dirección del servidor}:8000/google/callback

2. Agregar a .env:

   GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com
   GOOGLE_CLIENT_SECRET=GOCSPX-xxx
   MCP_SERVER_URL=http://localhost:8000   # 배포 시 실제 서버 URL로 변경

Método de ejecución:

1. Cambiar la configuración de Claude Code a http (ver más abajo)

2. Ejecutar el servidor MCP directamente:

   cd /path/to/mcp-aws-monitor
   .venv/bin/python -m src.server --http
   # Uvicorn running on http://0.0.0.0:8000

3. Iniciar (o reiniciar) Claude Code

4. Al invocar una herramienta MCP, se abrirá el navegador y se autenticará automáticamente después de iniciar sesión en Google

Para detener el servidor: Ctrl+C

Configuración de Claude Code (~/.claude.json o ~/.claude/.mcp.json):

{
  "mcpServers": {
    "aws-monitor": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

CLI de registro:

claude mcp add --transport http -s user aws-monitor http://localhost:8000/mcp

Precauciones:

• Si la pantalla de consentimiento OAuth de Google se configura como "Interna", solo las cuentas de la misma organización de Google Workspace pueden acceder

• El token se almacena en memoria, por lo que se requiere volver a iniciar sesión si se reinicia el servidor

• localhost solo es accesible desde la propia máquina. Para compartir en equipo, es necesario desplegar el servidor

Arquitectura

Flujo de operación (stdio)

Claude Code 세션 시작
  → MCP 서버 프로세스 실행 (src/server.py)
    → .env에서 AWS 키 로드 (python-dotenv)
    → FastMCP 인스턴스 생성
    → 각 모듈의 register_tools()로 도구 24개 등록
    → stdio 기반으로 Claude Code와 통신

Flujo de operación (HTTP + Google OAuth)

MCP 서버 실행 (uvicorn :8000)
  → .env에서 AWS 키 + Google OAuth 키 로드
  → FastMCP 인스턴스 생성 (AuthSettings 포함)
  → OAuth 엔드포인트 자동 마운트 (/authorize, /token, /register, /revoke)
  → /google/callback 라우트 추가
  → /mcp 엔드포인트에서 인증된 요청만 도구 실행

aws_client.py

Fábrica que almacena en caché los clientes boto3 con lru_cache. Crea y reutiliza un cliente una sola vez para el mismo servicio. Se invoca con get_client("nombre del servicio") desde todos los módulos.

Patrón de módulos

Todas las herramientas siguen el mismo patrón:

1. Obtener el cliente boto3 con get_client()

2. Llamar a la API de AWS

3. Convertir la respuesta a una cadena con formato en coreano y devolverla

Las herramientas MCP deben devolver un valor de tipo cadena, por lo que todas son -> str.

Herramientas proporcionadas (24)

CloudWatch (4)

cloudwatch_get_alarms

Consulta el estado de las alarmas de CloudWatch.

• state_filter (str, por defecto "ALL"): ALARM, OK, INSUFFICIENT_DATA, ALL

• Consulta tanto MetricAlarms como CompositeAlarms

• Devuelve el nombre de la alarma, la métrica asociada y el motivo del cambio de estado

cloudwatch_get_metric

Consulta datos de series temporales de una métrica específica.

• namespace (str): Espacio de nombres de AWS (ej: AWS/EC2, AWS/RDS)

• metric_name (str): Nombre de la métrica (ej: CPUUtilization)

• dimension_name (str): Nombre de la dimensión (ej: InstanceId)

• dimension_value (str): Valor de la dimensión (ej: i-0abc123)

• stat (str, por defecto "Average"): Average, Sum, Maximum, Minimum, SampleCount

• hours (int, por defecto 1): Rango de tiempo de consulta en horas

• El período se calcula automáticamente con un mínimo de 5 minutos y un máximo de 60 puntos de datos

cloudwatch_search_logs

Ejecuta una consulta de CloudWatch Logs Insights.

• log_group (str): Nombre del grupo de logs (ej: /ecs/logispot-api)

• query (str): Consulta de Insights

• hours (int, por defecto 1): Rango de tiempo de consulta en horas

• limit (int, por defecto 50): Límite de resultados

• Consulta asíncrona → sondea cada 1 segundo durante un máximo de 30 segundos esperando la finalización

• Si la consulta no tiene una cláusula limit, se agrega automáticamente

cloudwatch_list_log_groups

Lista los grupos de logs de CloudWatch.

• prefix (str, opcional): Filtro por prefijo del nombre del grupo de logs

• Obtiene la lista completa con un paginador

• Muestra el tamaño de almacenamiento (MB) de cada grupo de logs

SQS (3)

sqs_list_queues

Lista las colas SQS y consulta el número de mensajes.

• prefix (str, opcional): Filtro por prefijo del nombre de la cola

• Muestra el número de mensajes en espera (Visible), en proceso (NotVisible) y retrasados (Delayed) por cola

sqs_queue_detail

Consulta información detallada de una cola SQS.

• queue_name (str): Nombre de la cola

• Muestra ARN, número de mensajes, VisibilityTimeout, MessageRetentionPeriod

• Si existe RedrivePolicy, analiza y muestra el nombre de la DLQ y maxReceiveCount

sqs_peek_messages

Previsualiza mensajes de una cola SQS sin eliminarlos.

• queue_name (str): Nombre de la cola

• count (int, por defecto 5): Número de mensajes a consultar (máximo 10)

• Llama con VisibilityTimeout=0 para que los mensajes sean visibles inmediatamente de nuevo

• Muestra hasta 500 caracteres del cuerpo del mensaje

RDS (3)

rds_list_instances

Lista las instancias RDS y su estado.

• Sin parámetros

• Muestra por instancia: identificador, estado, motor/versión, clase, almacenamiento, Multi-AZ, Endpoint

rds_get_metrics

Consulta las métricas principales de una instancia RDS. Utiliza la API de CloudWatch.

• db_instance_id (str): Identificador de la instancia RDS

• hours (int, por defecto 1): Rango de tiempo de consulta en horas

• 7 métricas consultadas:

  • CPUUtilization (%)

  • DatabaseConnections (número)

  • FreeStorageSpace (convertido a GB)

  • ReadLatency / WriteLatency (segundos)

  • ReadIOPS / WriteIOPS

• Devuelve el valor del punto de datos más reciente de cada métrica

rds_slow_queries

Consulta las Top N consultas lentas con Performance Insights de RDS.

• db_instance_id (str): Identificador de la instancia RDS

• hours (int, por defecto 1): Rango de tiempo de consulta en horas

• limit (int, por defecto 10): Número de resultados

• Obtiene DbiResourceId con la API de RDS → consulta el ranking de consultas basado en db.load.avg con la API de PI

• Devuelve un resultado vacío para instancias con Performance Insights deshabilitado

S3 (4)

s3_list_buckets

Lista los buckets de S3.

• Sin parámetros

• Muestra el nombre del bucket y la fecha de creación

s3_list_objects

Lista los objetos dentro de un bucket de S3.

• bucket (str): Nombre del bucket

• prefix (str, opcional): Prefijo de ruta (ej: logs/2024/)

• limit (int, por defecto 30): Número de resultados

• Primero recorta con MaxKeys y luego ordena por LastModified en orden descendente

• Conversión automática del tamaño del archivo a KB/MB

s3_get_bucket_size

Calcula el tamaño total de un bucket de S3 o un prefijo.

• bucket (str): Nombre del bucket

• prefix (str, opcional): Prefijo de ruta

• Itera sobre todos los objetos con un paginador y los suma

• Devuelve el número de archivos y el tamaño total (con conversión automática a KB/MB/GB)

• Los buckets grandes pueden tardar mucho tiempo

s3_read_text_file

Lee el contenido de un archivo de texto de S3.

• bucket (str): Nombre del bucket

• key (str): Clave del archivo

• max_bytes (int, por defecto 10000): Máximo de bytes a leer

• Lee solo la parte inicial con el encabezado Range (seguro para archivos grandes)

• Decodifica con UTF-8, los caracteres rotos se reemplazan

EC2 / ECS / AutoScaling (5)

ec2_list_instances

Lista las instancias EC2.

• state_filter (str, por defecto "running"): running, stopped, all

• Muestra la etiqueta Name, ID de instancia, tipo, estado, AZ, IP privada/pública

ec2_get_cpu

Consulta la serie temporal de uso de CPU de una instancia EC2.

• instance_id (str): ID de la instancia EC2

• hours (int, por defecto 1): Tiempo de consulta en horas

• Muestra dos estadísticas juntas: Average y Maximum

ecs_list_clusters

Lista los clústeres de ECS.

• Sin parámetros

• Muestra por clúster: estado, número de servicios activos, número de tareas en ejecución/en espera

ecs_list_services

Lista los servicios dentro de un clúster de ECS y su estado.

• cluster (str): Nombre o ARN del clúster

• Muestra por servicio: estado, conteos Desired/Running/Pending, Task Definition

autoscaling_list_groups

Lista los grupos de Auto Scaling y su estado actual.

• Sin parámetros

• Muestra por grupo: número de instancias, configuración Min/Max/Desired, tipo de health check

SNS (2)

sns_list_topics

Lista los temas de SNS.

• Sin parámetros

• Muestra el nombre del tema y el ARN

sns_get_topic_subscriptions

Lista las suscripciones de un tema de SNS.

• topic_arn (str): ARN del tema (ej: arn:aws:sns:ap-northeast-2:123456:my-topic)

• Muestra por suscripción: Protocol, Endpoint, SubscriptionArn

Lambda (3)

lambda_list_functions

Lista las funciones Lambda.

• Sin parámetros

• Muestra el nombre de la función, Runtime, Description, LastModified

lambda_get_function

Consulta información detallada de una función Lambda.

• function_name (str): Nombre o ARN de la función

• Muestra información de configuración (Runtime, Handler, Memory, Timeout), claves de variables de entorno, mapeo de fuentes de eventos y política de recursos

lambda_get_code

Consulta el código fuente de una función Lambda.

• function_name (str): Nombre o ARN de la función

• Descarga el paquete de implementación y muestra el contenido de los archivos fuente (.py, .js, .ts, .json, etc.)

• Excluye directorios de dependencias como node_modules, pycache, etc.

Instalación

cd ~/work/mcp-aws-monitor
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Configuración

Ingrese las claves necesarias en el archivo .env:

# AWS (필수)
AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret
AWS_DEFAULT_REGION=ap-northeast-2

# Google OAuth (HTTP 모드 사용 시)
GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxx
MCP_SERVER_URL=http://localhost:8000

Consulte la sección Métodos de integración anterior para conocer cómo integrar con Claude Code.

Permisos IAM

Al crear un usuario IAM, adjunte la siguiente política en línea:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "cloudwatch:Describe*",
        "cloudwatch:Get*",
        "logs:Describe*",
        "logs:StartQuery",
        "logs:GetQueryResults",
        "sqs:List*",
        "sqs:Get*",
        "sqs:ReceiveMessage",
        "rds:Describe*",
        "pi:Describe*",
        "s3:List*",
        "s3:Get*",
        "ec2:Describe*",
        "ecs:List*",
        "ecs:Describe*",
        "autoscaling:Describe*",
        "lambda:List*",
        "lambda:Get*",
        "lambda:GetPolicy",
        "sns:List*",
        "sns:Get*"
      ],
      "Resource": "*"
    }
  ]
}

1. Consola de AWS → IAM → Usuarios → Crear usuario

2. Configuración de permisos → "Adjuntar políticas directamente" → Pegue la política anterior en la pestaña JSON

3. Después de crear el usuario, emita una clave de acceso (para uso CLI)

4. Ingrese la clave en .env

Limitaciones conocidas

• Solo admite una región (ap-northeast-2). No es posible consultar múltiples regiones

• Al listar EC2, RDS y AutoScaling, solo se devuelve la primera página (se trunca con grandes cantidades de recursos)

• s3_list_objects aplica el límite después de la ordenación básica de S3, por lo que puede no ser el N más reciente real

• Si la consulta de cloudwatch_search_logs no se completa en 30 segundos, puede devolver resultados incompletos

• En caso de error de la API de AWS, la excepción se expone directamente (falta de permisos, ID de recurso incorrecto, etc.)