CloudWatch MCP Server

Un servidor MCP personalizado, construido con FastMCP, que expone las métricas de Amazon CloudWatch, Logs Insights y Alarmas como herramientas que un asistente de IA puede llamar. Diseñado para ejecutarse localmente durante el desarrollo y para desplegarse en AWS Lambda como imagen de contenedor, accesible a través de una Function URL de Lambda.

Probado contra fastmcp==3.4.7 y boto3 con mocks de moto (todas las herramientas enumeradas abajo se probaron contra llamadas simuladas de CloudWatch/Logs). Fija tu propia versión de fastmcp en requirements.txt antes de desplegar y vuelve a revisar este README a la luz de gofastmcp.com si ha pasado tiempo — la API de FastMCP ha cambiado de forma más de una vez (consulta la sección «Una nota sobre la API cambiante de FastMCP», más abajo).

Herramientas expuestas

Todas las herramientas son de solo lectura — ninguna puede modificar, eliminar ni crear nada en CloudWatch. Mantenlo así a menos que haya una razón concreta para añadir acceso de escritura; el principio del mínimo privilegio importa mucho más cuando es un modelo de IA el que decide cuándo llamar a estas herramientas.

Related MCP server: cloudwatch-mcp

1. Ejecútalo primero en local

Esta es la forma más rápida de comprobar que las herramientas funcionan antes de tocar en absoluto el despliegue en AWS.

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Uses your normal AWS credentials (aws configure / AWS_PROFILE / SSO)
export AWS_PROFILE=your-profile
export AWS_REGION=us-east-1

python3 server.py   # defaults to stdio transport

Usa este comando directamente en un cliente MCP (Claude Desktop, Claude Code, etc.) — para Claude Desktop, añádelo a su configuración MCP:

{
  "mcpServers": {
    "cloudwatch": {
      "command": "/full/path/to/.venv/bin/python3",
      "args": ["/full/path/to/server.py"],
      "env": { "AWS_PROFILE": "your-profile", "AWS_REGION": "us-east-1" }
    }
  }
}

Para probar el transporte HTTP localmente (el modo que se usa en Lambda):

MCP_TRANSPORT=http PORT=8080 python3 server.py
# then, from another terminal:
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

2. IAM: qué puede tocar el servidor

El iam-policy.json de esta carpeta es el conjunto mínimo de permisos que el servidor necesita — GetMetricData/ListMetrics/DescribeAlarms* para CloudWatch, DescribeLogGroups/StartQuery/GetQueryResults/StopQuery para Logs Insights. Nada más. Adjunta esta política a la identidad que ejecute el servidor:

• Localmente: adjúntala a un usuario/rol de IAM y utilízala mediante AWS_PROFILE, o concédesela a tu rol SSO.

• En Lambda: adjúntala al rol de ejecución de la función Lambda (más el estándar AWSLambdaBasicExecutionRole para el registro de la propia función) —, nunca incrustes claves de acceso en la imagen.

3. Desplegar en AWS Lambda

La ruta recomendada por el propio CloudWatch para «exponer una función existente como una herramienta MCP sin código de protocolo» es Amazon Bedrock AgentCore Gateway — merece la pena echarle un vistazo si una opción totalmente gestionada te resulta aceptable más adelante. Lo que hay a continuación es la vía literal «se manage el servidor MCP»: usamos el AWS Lambda Web Adapter para que esta misma aplicación FastMCP se ejecute sin modificación dentro de Lambda.

Construir y subir la imagen de contenedor

aws ecr create-repository --repository-name cloudwatch-mcp-server

aws ecr get-login-password --region <region> | \
  docker login --username AWS --password-stdin <account-id>.dkr.ecr.<region>.amazonaws.com

docker build -t cloudwatch-mcp-server .
docker tag cloudwatch-mcp-server:latest \
  <account-id>.dkr.ecr.<region>.amazonaws.com/cloudwatch-mcp-server:latest
docker push <account-id>.dkr.ecr.<region>.amazonaws.com/cloudwatch-mcp-server:latest

Crear la función Lambda

1. Crea la función desde la imagen de contenedor que acabas de subir.

2. Memoria: empieza con 512 MB; timeout: 30 s es suficiente para la mayoría de las llamadas de métricas/alarmas; súbelo a 60–120 s si tus consultas de Logs Insights son grandes (el max_wait_seconds de query_logs debe quedar claramente por debajo del timeout de la función).

3. Adjunta el rol de ejecución con la política IAM del paso 2.

4. Define el modo de invocación con RESPONSE_STREAM si habilitas una Function URL con streaming (necesario para que el adaptador pueda proxear respuestas largas).

5. Crea una Function URL:

   • Tipo de autenticación: AWS_IAM (no uses NONE fuera de una prueba personal rápida — eso dejaría tus datos de CloudWatch al alcance de cualquiera que tenga la URL).

   • Tu cliente MCP tendrá que firmar las solicitudes con SigV4 para llamarla; la mayoría de los clientes MCP aún no lo hacen de forma nativa, así que en la práctica esto suele quedar detrás de algo que sí pueda firmar solicitudes — por ejemplo, una pasarela/proxy interna que controle tu equipo, o API Gateway con autenticación IAM delante de la Function URL en lugar de usar la autenticación IAM propia de la Function URL directamente.

6. El endpoint MCP será https://<function-url>/mcp.

Comprobación de la función desplegada

aws lambda invoke --function-name cloudwatch-mcp-server \
  --payload '{}' /tmp/out.json && cat /tmp/out.json

y luego una llamada MCP real de initialize contra la Function URL (con firmado SigV4, p. ej. mediante awscurl o un pequeño script de solicitudes firmadas) — el mismo cuerpo JSON que en la prueba curl local anterior.

4. Bordes ásperos conocidos (sé honesto con tu equipo sobre esto)

• Arranques en frío: un servidor HTTP completo (uvicorn + FastMCP) arrancando dentro de un cold start de Lambda es más lento que un handler típico y funcional — espera una latencia de varios segundos en la primera llamada después de un período de inactividad. La concurrencia preparada mitiga esto si importa en tu caso de uso.

• Sin push del servidor / sin sesión de larga duración: stateless_http=True significa que cada llamada de herramienta es una petición nueva e independiente: no se recuerda nada entre llamadas y el servidor no puede empujar mensajes al cliente de forma proactiva. Diseña las herramientas para que cada llamada lo contenga todo (este servidor ya lo hace, por ejemplo, query_logs recibe el rango de tiempos completo y el string de consulta en una sola llamada).

• La autenticación la pones tú: la autenticación IAM de la Function URL (o lo que pongas delante de ella) es lo único entre «asistente de IA» y «cualquiera con la URL». No la omitas, ni siquiera en pruebas tempranas, si la función puede tocar algo más que una cuenta sandbox desechable.

• Las consultas de Logs Insights se sondean, no se empujan: query_logs bloquea y hace polling a get_query_results hasta max_wait_seconds. En consultas muy grandes, esto puede invadir el límite Lambda — mantén las consultas acotadas (limit, rangos de tiempo estrechos) en lugar de abiertas.

5. Nota sobre la API cambiante de FastMCP

FastMCP ha cambiado su API HTTP/stateless más de una vez entre versiones (el flag stateless_http se ha movido entre el constructor de FastMCP() y mcp.run()/mcp.http_app() en distintas versiones). El código en server.py se verificó contra fastmcp==3.4.7 (mcp.run(transport="http", stateless_http=True, ...)). Si subes la versión y algo se rompe, consulta primero gofastmcp.com/deployment/http — es lo que más probablemente haya cambiado.