6. Q CLI 기반 MCP 구성하기 3

update : 2025.06.04

Amazon EKS MCP Server

Amazon EKS MCP Server는 AI 코드 어시스턴트가 EKS 클러스터를 생성, 운영, 문제 해결할 수 있도록 지원하는 리소스 관리 및 상태 가시화 서버입니다.

이 MCP 서버는 LLM 기반 어시스턴트에게 컨텍스트 인식 기능과 실시간 오퍼레이션 제어 기능을 제공하여, 클러스터 셋업부터 배포, 디버깅에 이르는 전 과정을 자연어 기반으로 안내할 수 있도록 도와줍니다.

1. 주요 효과

  • 클러스터 생성, 배포, 운영, 디버깅까지 전체 워크플로우를 단순화

  • LLM 기반 AI 코드 어시스턴트의 실시간 리소스 관리 능력 향상

  • 자연어 요청만으로 클러스터 설정 및 운영을 자동화

2. 핵심 기능

1. 클러스터 생성 자동화

  • 전용 VPC, 네트워킹, EKS Auto Mode 노드풀 등을 포함한 EKS 클러스터를 생성

  • 사용자의 자연어 요청을 AWS CloudFormation 액션으로 변환

2. 애플리케이션 배포 지원

  • 기존 Kubernetes YAML 파일을 적용하거나,

  • 사용자 입력에 따라 Deployment 및 Service 매니페스트를 자동 생성

3. Kubernetes 리소스 라이프사이클 관리

  • Pod, Service, Deployment 등의 리소스에 대해 생성(Create), 조회(Read), 수정(Update), 패치(Patch), 삭제(Delete) 지원

4. 리소스 상태 정보 조회

  • 네임스페이스, 라벨, 필드 기준으로 Kubernetes 리소스를 필터링하여 조회 가능

  • EKS 인프라 및 애플리케이션 상태 파악을 간소화

5. 운영 및 디버깅 지원

  • 특정 Pod 또는 컨테이너의 로그 조회

  • 관련된 Kubernetes 이벤트를 추출하여 원인 분석 지원

6. 문제 해결 자동화

  • EKS 클러스터에서 발생하는 이슈에 대한 진단 및 해결을 위한 디버깅 툴 내장

  • LLM이 상황을 파악하고 적절한 해결 절차를 안내

아래는 GitBook 스타일로 재구성한 Prerequisites & Setup 문서입니다. 문단 구분과 계층적 구조, 설명을 모두 포함하여 실습 전에 필요한 모든 요소를 명확히 정리했습니다.

Prerequisites & Setup

Amazon EKS MCP Server를 사용하기 위해서는 다음과 같은 사전 준비가 필요합니다.

3. Prerequisites

1-1. Python 환경 구성

  • Python 3.10 이상을 설치합니다.

python3 --version

1-2. uv 패키지 매니저 설치

  • uv는 Python 프로젝트의 빠른 패키지 설치를 위한 도구입니다.

    설치 방법:

curl -Ls https://astral.sh/uv/install.sh | sh

1-3. AWS CLI 설치 및 설정

  • AWS CLI를 설치하고 자격 증명을 구성합니다.

aws configure

  • Access Key / Secret Key / Region / Output Format 입력

  • EKS 클러스터 리소스를 제어하는 IAM 사용자 또는 역할로 설정

4. IAM Policy 설정

EKS MCP Server를 통해 EKS 리소스를 읽거나 제어하기 위해서는 IAM 권한 설정이 필요합니다.

2-1. Read-Only Operations Policy

클러스터 상태 조회 및 리소스 읽기 작업을 위한 최소 권한입니다:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "eks:DescribeCluster",
        "eks:ListClusters",
        "eks:AccessKubernetesApi",
        "iam:ListRoles",
        "cloudformation:DescribeStacks",
        "cloudformation:ListStacks",
        "ec2:DescribeSubnets",
        "ec2:DescribeVpcs",
        "ec2:DescribeSecurityGroups"
      ],
      "Resource": "*"
    }
  ]
}

위 정책은 MCP Server가 클러스터 정보, 네트워크 구성, IAM 역할 등을 읽을 수 있도록 해줍니다.

다음은 GitBook 문서 스타일로 정리한 Write Operations Policy 및 Kubernetes API Access Requirements 섹션입니다. 보안 주의사항도 강조해 포함하였습니다.

Write Operations Policy

EKS MCP Server를 통해 EKS 클러스터를 CloudFormation 템플릿(/awslabs/eks_mcp_server/templates/eks-templates/eks-with-vpc.yaml) 기반으로 생성 및 배포하려면 다음 IAM 정책이 필요합니다.

5.권장 IAM 정책

1. IAMFullAccess

  • 클러스터 운영에 필요한 IAM 역할 및 정책을 생성하고 관리할 수 있도록 허용

2. AmazonVPCFullAccess

  • 서브넷, 라우팅 테이블, IGW, NAT Gateway 등 VPC 리소스를 생성 및 구성 가능

3. AWSCloudFormationFullAccess

  • CloudFormation 스택을 생성, 업데이트, 삭제할 수 있도록 허용

4. EKS Full Access

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "eks:*",
      "Resource": "*"
    }
  ]
}

위 정책은 EKS 클러스터, 노드 그룹, 애드온 등 전반적인 클러스터 리소스를 생성 및 제어할 수 있게 합니다.

6. ⚠️ Important Security Note

  • --allow-write 또는 --allow-sensitive-data-access 플래그를 사용할 경우, MCP 서버에 매우 강력한 권한이 부여됩니다.

  • 신뢰할 수 있는 환경에서만 이 기능을 활성화해야 하며, 프로덕션 환경에서는 제한된 Custom Policy 사용을 권장합니다.

  • 보안 원칙: 최소 권한(Least Privilege) 기반의 정책 설계를 고려하세요.

Kubernetes API Access Requirements

EKS MCP Server가 Kubernetes API(예: Pod 생성, 로그 조회 등)를 사용하기 위해서는 다음 중 하나의 조건을 충족해야 합니다.

조건 1: 클러스터 생성자

  • 해당 EKS 클러스터를 생성한 IAM 주체(IAM Role 또는 User)가 API를 호출하는 경우

조건 2: Access Entry 구성

  • API 호출 대상 클러스터에 대해 EKS Access Entry가 해당 사용자 또는 역할에 대해 명시적으로 구성되어 있어야 함

# 예시: EKS Access Entry 구성 확인
aws eks describe-access-entry --cluster-name <your-cluster> --principal-arn <your-iam-role-arn>

⚠️ Kubernetes API 호출 시 authorization error가 발생하면 위 조건을 만족하는지 확인하세요.

Quickstart: Amazon EKS MCP Server

이 가이드는 Amazon EKS MCP Server를 Cursor IDE와 Amazon Q Developer CLI에서 활용할 수 있도록 설정하는 과정을 안내합니다. 설정을 완료하면, EKS 클러스터 및 Kubernetes 리소스를 자연어 기반 명령으로 손쉽게 관리할 수 있습니다.

7. Cursor IDE 설정

1-1. MCP 서버 추가

  1. Cursor를 실행합니다.

  2. 오른쪽 상단의 ⚙️ 설정 아이콘을 클릭합니다.

  3. 좌측 메뉴에서 MCP > Add new global MCP server 클릭

  4. 아래와 같이 EKS MCP 서버 정의를 붙여넣습니다:

{
  "mcpServers": {
    "awslabs.eks-mcp-server": {
      "autoApprove": [],
      "disabled": false,
      "command": "uvx",
      "args": [
        "awslabs.eks-mcp-server@latest",
        "--allow-write"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "transportType": "stdio"
    }
  }
}

✅ --allow-write 플래그는 리소스 생성/수정/삭제 기능을 허용합니다. 신뢰된 환경에서만 사용하세요.

  1. 수 분 내에 MCP 서버가 정상 등록되면 녹색 표시(Green indicator)가 나타납니다.

1-2. 프롬프트 실행

  • Ctrl + L (또는 ⌘ + L)을 눌러 Cursor의 채팅 패널을 엽니다.

  • 다음과 같은 프롬프트를 입력해보세요:

‘ap-northeast-2’ 리전에 Kubernetes 버전 1.31을 사용하여 이름이 ‘my-test-cluster’인 새로운 EKS 클러스터를 생성하세요.

8. Amazon Q Developer CLI 설정

2-1. Q CLI 설치

  • 공식 문서 또는 npm, brew 등으로 Amazon Q Developer CLI를 설치합니다. (앞선 실습에서 이미 설치했습니다.)

2-2. MCP 서버 구성

  1. MCP 설정 파일 mcp.json을 엽니다 (예: ~/.aws/amazonq/mcp.json).

  2. 아래 내용을 추가합니다:

{
  "mcpServers": {
    "awslabs.eks-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.eks-mcp-server@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "autoApprove": [],
      "disabled": false
    }
  }
}

  • 아래는 실습에서 사용되는 mcp 3개를 합친 JSON 입니다.

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["mcp-server-kubernetes"]
    },
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--headless",
        "--executable-path",
        "/usr/bin/google-chrome-stable"
      ]
    },
    "awslabs.eks-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.eks-mcp-server@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "autoApprove": [],
      "disabled": false
    }
  }
}

  1. 설정을 저장하고, 다음 명령으로 MCP 도구 목록을 확인합니다:

/tools

다음은 GitBook 스타일로 구성한 Amazon EKS MCP Server 설정 가이드 - Configurations 섹션입니다. 각 설정 요소에 대해 설명과 예제를 함께 제공합니다.

Configurations

Amazon EKS MCP Server는 실행 시 다양한 인자(arguments)와 환경 변수(environment variables)를 통해 동작 방식을 설정할 수 있습니다. 이 섹션에서는 args 및 env 필드를 사용하는 방법을 다룹니다.

9. Arguments

args 필드는 MCP 서버 실행 시 전달되는 명령줄 인자를 정의합니다. 각 인자는 MCP 서버의 기능 활성화 및 동작 모드에 영향을 줍니다.

✅ 예시

{
  "mcpServers": {
    "awslabs.eks-mcp-server": {
      "command": "uvx",
      "args": [
        "awslabs.eks-mcp-server@latest",
        "--allow-write",
        "--allow-sensitive-data-access"
      ],
      "env": {
        "AWS_PROFILE": "your-profile",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

🔹 필수 인자

  • awslabs.eks-mcp-server@latest

    • MCP 클라이언트의 최신 패키지/버전 지정자입니다.

    • MCP 서버를 실행하고 도구를 등록하는 데 사용됩니다.

🔹 선택 인자

  • --allow-write

    • Kubernetes 리소스에 대해 생성/수정/삭제(mutate) 작업을 허용합니다.

    • 대상 도구: apply_yaml, generate_app_manifest, manage_k8s_resource, manage_eks_stacks, add_inline_policy 등

    • 기본값: false (기본은 읽기 전용 모드)

    • 예시:

"args": ["awslabs.eks-mcp-server@latest", "--allow-write"]

  • --allow-sensitive-data-access

    • 로그, 이벤트, Kubernetes Secrets 등의 민감한 데이터 접근을 허용합니다.

    • 기본값: false (기본적으로 민감 데이터는 비활성화)

    • 예시:

"args": ["awslabs.eks-mcp-server@latest", "--allow-sensitive-data-access"]

아래는 GitBook 스타일로 정리한 Amazon EKS MCP Server의 Tools 소개 섹션입니다. 각 도구는 기능별로 분류되어 있으며, 주요 기능(Features)과 사용 가능한 파라미터(Parameters)를 함께 제공합니다.

Tools

Amazon EKS MCP Server는 EKS 클러스터와 Kubernetes 리소스를 효율적으로 관리하기 위한 다양한 도구를 제공합니다. 각 도구는 특정 작업을 자동화하며, AI 코드 어시스턴트 또는 CLI를 통해 호출할 수 있습니다.

10. EKS Cluster Management

🔧 manage_eks_stacks

CloudFormation 기반으로 EKS 클러스터와 관련 인프라를 생성, 설명, 삭제하는 도구입니다.

  • Features

    • 지정한 클러스터 이름을 포함한 CloudFormation 템플릿 생성

    • VPC, Subnet, NAT Gateway, IAM Role, 노드 풀 등을 포함한 클러스터 배포

    • 기존 스택 상세 조회 (상태, 출력 값, 생성 시간 등)

    • 스택 삭제 및 자원 정리 (단, 이 도구로 생성한 스택만 대상으로 함)

  • Parameters

    • operation (generate, deploy, describe, delete)

    • template_file

    • cluster_name

11. Kubernetes Resource Management

🔧 manage_k8s_resource

개별 Kubernetes 리소스를 생성, 수정, 삭제, 조회하는 도구입니다.

  • Features

    • create, replace, patch, delete, read 등 Kubernetes 리소스 조작

    • Namespace가 필요한 리소스 및 불필요한 리소스 모두 처리 가능

  • Parameters

    • operation, cluster_name, kind, api_version, name, namespace(optional), body

🔧 apply_yaml

YAML 매니페스트를 클러스터에 적용하는 도구입니다.

  • Features

    • multi-document YAML 파일 지원

    • 전체 매니페스트를 지정된 namespace에 적용

    • force: true로 기존 리소스 덮어쓰기 가능

  • Parameters

    • yaml_path, cluster_name, namespace, force

🔧 list_k8s_resources

지정된 리소스 종류(Kubernetes kind)의 목록을 반환합니다.

  • Features

    • 메타데이터 요약 포함

    • namespace, label, field 기반 필터링 지원

  • Parameters

    • cluster_name, kind, api_version, namespace, label_selector, field_selector

🔧 list_api_versions

클러스터에서 사용 가능한 모든 API 버전을 나열합니다.

  • Features

    • core API (v1) 및 group API (apps/v1, networking.k8s.io/v1) 포함

  • Parameters

    • cluster_name

12. Application Support

🔧 generate_app_manifest

애플리케이션 배포용 Deployment 및 Service 매니페스트를 생성합니다.

  • Features

    • 로드 밸런서 구성, 리소스 요청/제한 설정 지원

    • 지정한 디렉토리로 YAML 출력

  • Parameters

    • app_name, image_uri, output_dir, port, replicas, cpu, memory, namespace, load_balancer_scheme

🔧 get_pod_logs

Pod의 로그를 조회합니다.

  • Features

    • 시간, 라인 수, 바이트 수 기준 필터링

    • 컨테이너별 로그 선택 가능

    • --allow-sensitive-data-access 필요

  • Parameters

    • cluster_name, pod_name, namespace, container_name, since_seconds, tail_lines, limit_bytes

🔧 get_k8s_events

특정 리소스에 대한 Kubernetes 이벤트를 조회합니다.

  • Features

    • 이벤트 시간, 메시지, 이유, 횟수 등의 상세 정보 제공

    • namespaced/비-namespaced 모두 지원

    • --allow-sensitive-data-access 필요

  • Parameters

    • cluster_name, kind, name, namespace

13. CloudWatch Integration

🔧 get_cloudwatch_logs

EKS 클러스터 내 자원에 대한 CloudWatch 로그를 조회합니다.

  • Features

    • 로그 타입(application, host 등)과 자원 종류(pod, node 등) 기반 조회

    • 시간 범위, 필터 패턴, 출력 필드 등 지정 가능

    • --allow-sensitive-data-access 필요

  • Parameters

    • cluster_name, log_type, resource_type, resource_name, minutes, start_time, end_time, limit, filter_pattern, fields

🔧 get_cloudwatch_metrics

CloudWatch 지표를 조회합니다.

  • Features

    • 자원별 메트릭, namespace, 통계(stat), 기간 설정 가능

    • Custom dimension으로 세밀한 쿼리 구성 가능

  • Parameters

    • cluster_name, metric_name, resource_type, resource_name, namespace, k8s_namespace, minutes, start_time, end_time, limit, stat, period, custom_dimensions

14. IAM Integration

🔧 get_policies_for_role

지정한 IAM 역할에 연결된 정책을 조회합니다.

  • Features

    • Assume role 정책 문서, 연결된 관리형 정책 및 인라인 정책 모두 반환

  • Parameters

    • role_name

🔧 add_inline_policy

새로운 인라인 정책을 IAM 역할에 추가합니다. 기존 정책은 수정하지 않습니다.

  • Features

    • 기존 정책 이름과 충돌 시 요청 거부

    • JSON 객체 또는 배열 형태로 권한 정의

    • --allow-write 필요

  • Parameters

    • policy_name, role_name, permissions (JSON object or array)

15. Troubleshooting

🔧 search_eks_troubleshoot_guide

  • 기능 : EKS 운영 중 발생할 수 있는 오류나 이슈에 대해 AWS 공식 가이드 기반의 해결책을 제공합니다.

  • 주요 사례

    • EKS Auto Mode 노드 생성 실패

    • Bootstrap 오류

    • Controller 장애 등

  • 출력 내용

    • 증상 설명 (Symptoms)

    • 단기 해결책 (Short-term Fixes)

    • 장기 해결책 (Long-term Fixes)

  • 파라미터

    • query: 해결하고자 하는 문제에 대한 키워드

Security & Permissions

16. 보안 기능

  • AWS 인증: 환경 변수에서 AWS 자격 증명을 불러와 사용

  • Kubernetes 인증: Kubernetes API를 위한 임시 자격 증명 생성

  • SSL 검증: 모든 Kubernetes API 호출 시 SSL 인증 필수

  • 리소스 태깅: 생성된 모든 리소스에 태그 추가

  • 최소 권한 원칙: 필요한 권한만 갖는 IAM Role을 사용

  • 스택 보호: 해당 MCP 툴로 생성된 스택만 수정/삭제 가능

  • 클라이언트 캐싱: TTL 기반의 클라이언트 보안 캐시 적용

17.고려 사항

  • EKS 리소스를 조작할 수 있는 AWS 자격 증명 필요

  • Kubernetes API 접근을 위한 임시 권한 자동 생성

  • VPC 및 보안 그룹 설정 필요

  • RBAC 설정을 통한 Kubernetes 자원 접근 제어

  • Kubernetes Secrets에 민감 정보 암호화 저장

  • EKS 클러스터의 로깅 및 모니터링 활성화 권장

18. 운영 모드별 권한 비교

모드

사용 가능 도구

Read-only (기본값)

manage_eks_stacks(describe), manage_k8s_resource(read), list_k8s_resources, get_pod_logs, get_k8s_events, get_cloudwatch_logs, get_cloudwatch_metrics, get_policies_for_role, search_eks_troubleshoot_guide, list_api_versions

Write-access (--allow-write 필요)

manage_eks_stacks(generate, deploy, delete), manage_k8s_resource(create, replace, patch, delete), apply_yaml, generate_app_manifest, add_inline_policy

✅ Auto Approve 설정 (Optional)

autoApprove 필드는 사용자의 승인 없이 지정된 MCP 도구를 자동 실행할 수 있도록 설정합니다.

"autoApprove": [
  "manage_eks_stacks",
  "manage_k8s_resource",
  "list_k8s_resources",
  "get_pod_logs",
  "get_k8s_events",
  "get_cloudwatch_logs",
  "get_cloudwatch_metrics",
  "get_policies_for_role",
  "search_eks_troubleshoot_guide",
  "list_api_versions"
]

19. IAM Permissions Management

🔧 add_inline_policy

  • 기능

    • 누락된 권한을 자동으로 부여할 수 있는 인라인 정책 생성 도구

    • 기존 정책 수정은 불가 (새로 추가만 허용)

  • 주의

    • --allow-write 활성화 필요

    • 권한 과다 부여 방지를 위해 사전 정의된 IAM Role 사용 권장

20. Role Scoping Recommendations

  • 전용 IAM Role을 생성하여 EKS MCP Server에서만 사용

  • 읽기 전용 / 쓰기 전용 Role 분리

  • CloudTrail로 모든 API 호출 감사

  • 정기 권한 리뷰 및 IAM Access Analyzer 활용

  • 리소스 태깅 기반 제한 정책 적용

21. 민감 정보 처리 주의사항

❗ 중요: MCP 서버를 통해 민감 정보를 직접 전달하지 마세요

  • 허용되지 않는 민감 정보 전달 방식

    • apply_yaml로 Secrets 포함 YAML 적용

    • 프롬프트에 비밀번호, 키 등을 직접 입력

    • CloudFormation 템플릿에 민감 정보 포함

  • 권장 방식

    • AWS Secrets Manager 또는 Parameter Store 사용

    • IRSA (IAM Roles for Service Accounts) 활용

    • 적절한 RBAC 설정으로 민감 정보 접근 제한

운영 및 관리 모범 사례

  • 이름 명확화: 클러스터 및 리소스에 의미 있는 이름 부여

  • 네임스페이스 분리: 기능 또는 팀 단위로 리소스 구분

  • 오류 처리: 도구 응답에 오류 포함 시 적절한 예외 처리

  • 자원 정리: 사용하지 않는 리소스는 삭제하여 비용 절감

  • 모니터링: EKS 및 Kubernetes 리소스 상태 주기적 확인

  • 보안: EKS 보안 모범 사례 준수

  • 백업: 중요한 리소스는 정기적으로 백업 수행

일반 문제 해결 팁

증상

확인 사항

Permission Error

AWS 자격 증명이 적절한 권한을 갖고 있는지 확인

CloudFormation Error

CloudFormation 콘솔에서 스택 오류 메시지 확인

Kubernetes API Error

클러스터가 실행 중이고 접근 가능한지 확인

Network Issue

VPC/Subnet/Security Group 구성 점검

MCP Client Error

MCP 서버 구성 또는 포트 확인

로그 부족

로그 레벨을 DEBUG로 설정하여 상세 로그 확보

Previous5. Q CLI 기반 MCP 구성하기 2Next7. EKS 활용 사례 1 (조회)

Last updated