CloudWatch MCP Server

커스텀 MCP 서버로, FastMCP로 빌드되었으며 Amazon CloudWatch Metrics, Logs Insights, Alarms를 AI 어시스턴트가 호출할 수 있는 도구로 노출합니다. 로컬에서 개발용으로 실행할 수 있고, AWS Lambda에 컨테이너 이미지로 배포한 뒤 Lambda Function URL 앞에서 제공되도록 설계되었습니다.

fastmcp==3.4.7과 boto3를 moto 모의(mock) 환경으로 테스트했습니다(아래 나열된 모든 도구는 모킹된 CloudWatch/Logs 호출로 검증했습니다). 배포 전에 requirements.txt에 자신의 fastmcp 버전을 명시적으로 고정하세요. 오랜 시간이 지났다면 이 README를 gofastmcp.com가 다시 확인하세요 — FastMCP의 API는 한 번 이상 모양이 바뀌어 왔습니다(아래 "FastMCP의 변동이 잦은 API에 대한 참고 사항" 섹션 참조).

노출되는 도구

모든 도구는 읽기 전용입니다. 어느 도구도 CloudWatch에서 아무것도 수정·삭제·생성할 수 없습니다. 쓰기 권한을 추가해야 하는 특별한 이유가 없다면 그 상태를 유지하세요. AI 모델이 어떤 도구를 호출할지 판단하는 상황이 되면 최소 권한(least privilege) 원칙이 훨씬 중요해집니다.

Related MCP server: cloudwatch-mcp

1. 먼저 로컬에서 실행하기

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

MCP 클라이언트(Claude Desktop, Claude Code 등)를 이 명령에 직접 연결하세요. Claude Desktop이라면 MCP config에 다음을 추가하세요:

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

HTTP 트랜스포트를 로컬에서 테스트하려면(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: 서버가 접근할 수 있는 범위

이 폴더의 iam-policy.json은 서버에 필요한 최소 권한 집합입니다. CloudWatch에는 GetMetricData/ListMetrics/DescribeAlarms*, Logs Insights에는 DescribeLogGroups/StartQuery/GetQueryResults/StopQuery 만 포함하며 그 밖에는 없습니다. 서버를 실행하는 주체(identity)에 이를 부여하세요:

• 로컬에서: IAM user나 role에 부여하고 AWS_PROFILE로 사용하거나, SSO role에 부여합니다.

• Lambda에서: Lambda 함수의 **실행 역할(execution role)**에 부여합니다(함수 자체 로깅용 표준 AWSLambdaBasicExecutionRole 포함). access 코드를 이미지에 절대넣지 마세요.

3. AWS Lambda에 배포

CloudWatch가 "프로토콜 코드 없이 기존 함수를 MCP 도구로 노출하는" 경로로 직접 권장하는 것은 Amazon Bedrock AgentCore Gateway입니다. 이후에 완전 관리형 옵션이 괜찮아진다면 고려할 만합니다. 아래는 말 그대로 "우리가 MCP 서버를 직접 소유"하는 경로이며, AWS Lambda Web Adapter를 사용해 이 동일한 FastMCP 앱을 Lambda에서 수정 없이 실행할 수 있습니다.

컨테이너 이미지 빌드 및 푸시

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

Lambda 함수 생성

1. 방금 푸시한 컨테이너 이미지로 함수를 생성합니다.

2. 메모리는 512MB로 시작하세요. 타임아웃은 대부분의 지표/알람 호출에 30초로 충분하며, Logs Insights 쿼리가 큰 경우 60–120초로 늘리세요(query_logs의 max_wait_seconds는 함수 타임아웃보다 한층 낮게 유지해야 합니다).

3. 2단계의 IAM 정책이 포함된 execution role을 연결합니다.

4. 스트리밍 기능을 가진 Function URL을 활성화하는 경우 Invoke mode를 RESPONSE_STREAM으로 설정합니다(어댑터가 긴 응답을 프록시하기 위해 필요합니다).

5. Function URL 생성:

   • 인증 유형: AWS_IAM (빠른 개인 테스트 이외에는 NONE을 사용하지 마세요. URL을 아는 사람이라면 누구든 CloudWatch 데이터에 접근할 수 있게 됩니다.)

   • MCP 클라이언트는 호출하기 위해 SigV4로 요청에 서명해야 합니다. 아직 대부분의 MCP 클라이언트가 이를 기본 지원하지 않으므로, 실제로는 요청에 서명할 수 있는 무언가 뒤에 두는 것이 일반적입니다 — 예: 팀이 관리하는 내부 gateway/proxy, 또는 Function URL 자체의 IAM 인증을 직접 사용하는 대신 API Gateway를 Function URL 앞에 두고 IAM 인증을 사용하는 방식.

6. MCP endpoint는 https://<function-url>/mcp입니다.

배포된 함수 정상 동작 확인

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

그리고 Function URL에 실제 MCP initialize 호출(SigV4 서명 필요, 예: awscurl 또는 간단한 signed-request script)을 보내면 됩니다 — 위 로컬 curl 테스트와 동일한 JSON body입니다.

4. 알려진 한계 (팀에 솔직하게 공유하세요)

• 콜드 스타트(cold start): 전체 HTTP 서버(uvicorn + FastMCP)가 Lambda 콜드 스타트에서 부팅되는 것은 일반적인 가벼운 Lambda 핸들러보다 느립니다. 유휴 상태 후 첫 호출에서 수 초 대기 시간이 생길 수 있습니다. 사용 사례에 중요하다면 프로비전된 동시성(Provisioned Concurrency)으로 완화할 수 있습니다.

• 서버 푸시 없음/장기 세션 없음: stateless_http=True이면 모든 도구 호출이 새롭고 독립적인 요청입니다. 호출 간에 아무것도 기억되지 않으며, 서버가 클라이언트에게 메시지를 능동적으로 푸시할 수 없습니다. 각 호출이 필요한 모든 것을 담고 있도록 도구를 설계하세요(이 서버는 이미 그렇게 합니다 — 예: query_logs는 전체 시간 범위와 쿼리 문저를 한 호출에 다 담습니다).

• 인증은 사용자 책임: Function URL의 IAM 인증(또는 그 앞에 둔 어떤 것)은 'AI 어시스턴트'와 'URL을 아는 누구나' 사이의 유일한 경계입니다. 함수가 일회용 샌드박스 계정 이상의 데이터에 접촉한다면 초기 테스트에서라도 이를 생략하지 마세요.

• Logs Insights 쿼리는 푸시가 아니라 폴링 방식: query_logs는 max_wait_seconds까지 get_query_results를 폴링하면서 대기합니다. 쿼리가 매우 크면 Lambda 타임아웃을 초과할 수 있습니다. 쿼리를 제한적인 범위로 유지하고(limit, 좁은 시간 범위) 한정 없이 열어두지 마세요.

5. FastMCP의 변동이 잦은 API에 대한 참고 사항

FastMCP는 버전마다 HTTP/stateless API를 한 번 이상 변경했습니다. stateless_http 플래그는 릴리스 버전에 따라 (some 최초 버전에서는 FastMCP() 생성자와 mcp.run()) 사이를 오갔고, 다른 릴리스에서는 mcp.http_app() 등으로 바뀌었습니다. server.py의 코드는 fastmcp==3.4.7 기준으로 검증되었습니다(mcp.run(transport="http", stateless_http=True, ...)). 버전을 올리고 무언가 깨진다면 먼저 gofastmcp.com/deployment/http를 확인해 보세요. 가장 흔한 변경 지점입니다.