Amazon EKS MCP Server 시작하기

이 가이드는 EKS MCP Server를 AI 코드 어시스턴트와 함께 설정하고 사용하는 단계를 안내합니다. 환경을 구성하고 서버에 연결하며 자연어 상호작용을 통해 EKS 클러스터 관리를 시작하는 방법을 배우게 돼요.

참고

Amazon EKS MCP Server는 Amazon EKS의 프리뷰 릴리스이며 변경될 수 있습니다.

사전 조건 (Prerequisites)

시작하기 전에 다음 작업을 수행했는지 확인하세요.

Amazon EKS에 접근 권한이 있는 AWS 계정 생성
자격 증명으로 AWS CLI 설치·구성
Python 3.10+ 설치
uv 설치

설정 (Setup)

1. 사전 조건 확인

# Check that your Python version is 3.10 or higher
python3 --version

# Check uv installation
uv --version

# Verify CLI configuration
aws configure list

2. IAM 권한 설정

EKS MCP 서버에 연결하려면 IAM 역할에 다음 정책이 연결되어 있어야 합니다. eks-mcp:InvokeMcp(초기화와 사용 가능한 도구 정보 검색에 필요한 권한), eks-mcp:CallReadOnlyTool(읽기 전용 도구 사용에 필요한 권한), eks-mcp:CallPrivilegedTool(전체 접근(쓰기) 도구 사용에 필요한 권한)입니다. 이러한 eks-mcp 권한은 아래 제공된 읽기 전용 및 전체 접근 AWS 관리형 정책에 포함되어 있어요.

IAM 콘솔을 엽니다.

왼쪽 탐색 창에서 정책을 연결하려는 자격 증명에 따라 Users, User groups, Roles를 선택한 다음, 특정 사용자, 그룹, 또는 역할의 이름을 선택합니다.

Permissions 탭을 선택합니다.

Attach policies를 선택합니다(처음이라면 Add permissions).

정책 목록에서 연결하려는 관리형 정책을 검색해서 선택합니다.

읽기 전용 작업: AmazonEKSMCPReadOnlyAccess

Attach policies(또는 확인하려면 Next 후 Add permissions)를 선택합니다.

이렇게 하면 정책이 연결되고 권한이 즉시 적용돼요. 같은 자격 증명에 여러 정책을 연결할 수 있으며 각 정책은 다양한 권한을 포함할 수 있습니다. 이 정책들에 대해 자세히 알아보려면 AWS managed policies for Amazon Elastic Kubernetes Service를 참고하세요.

3. AI 어시스턴트 선택

다음 MCP 호환 AI 어시스턴트 중 하나 또는 어떤 MCP 호환 도구든 선택하세요.

Amazon Q Developer CLI 설치
Kiro 설치
Cursor 설치
Cline VS Code Extension 설치

1단계: AI 어시스턴트 구성

다음 옵션 중 하나를 선택해서 AI 코드 어시스턴트를 설정하세요. 이 단계를 완료하면 Amazon EKS MCP Server에 대한 안전하고 인증된 접근에 필요한 MCP Proxy for AWS를 사용하도록 AI 코드 어시스턴트가 설정됩니다. 여기에는 MCP 구성 파일(예: Amazon Q Developer CLI의 ~/.aws/amazonq/mcp.json)을 추가하거나 편집하는 것이 포함됩니다. 프록시는 클라이언트 측 브리지 역할을 하며, 로컬 AWS 자격 증명으로 AWS SigV4 인증을 처리하고 EKS MCP Server 같은 백엔드 AWS MCP 서버와 상호작용하기 위한 동적 도구 발견을 가능하게 해요. 자세한 내용은 MCP Proxy for AWS 저장소를 참고하세요.

옵션 A: Amazon Q Developer CLI

Q Developer CLI는 EKS MCP Server와 가장 통합된 경험을 제공합니다.

MCP 구성 파일 찾기

macOS/Linux: ~/.aws/q/mcp.json
Windows: %USERPROFILE%\.aws\q\mcp.json

MCP 서버 구성 추가

파일이 없으면 만드세요. 리전({region}) 플레이스홀더를 원하는 리전으로 바꾸세요.

Mac/Linux의 경우:

{
  "mcpServers": {
    "eks-mcp": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://eks-mcp.{region}.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "default",
        "--region",
        "{region}"
      ]
    }
  }
}

Windows의 경우:

{
  "mcpServers": {
    "eks-mcp": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "mcp-proxy-for-aws@latest",
        "mcp-proxy-for-aws.exe",
        "https://eks-mcp.{region}.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "default",
        "--region",
        "{region}"
      ]
    }
  }
}

보안 참고: --read-only는 읽기 전용 도구 작업만 허용하도록 사용할 수 있습니다.

구성 확인

Q Developer CLI를 재시작한 다음 사용 가능한 도구를 확인합니다.

q /tools

옵션 B: Kiro IDE

Kiro는 내장 MCP 지원이 있는 AI 우선 코딩 작업 공간입니다.

Kiro 설정 열기

Kiro 열기
Kiro → Settings로 가서 "MCP Config"를 검색
또는 Cmd+Shift+P(Mac) 또는 Ctrl+Shift+P(Windows/Linux)를 누르고 "MCP Config"를 검색

MCP 서버 구성 추가

"Open Workspace MCP Config" 또는 **"Open User MCP Config"**를 클릭해서 MCP 구성 파일을 직접 편집합니다.

리전({region}) 플레이스홀더를 원하는 리전으로 바꾸세요.

Mac/Linux:

{
  "mcpServers": {
    "eks-mcp": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://eks-mcp.{region}.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "default",
        "--region",
        "{region}"
      ]
    }
  }
}

Windows:

{
  "mcpServers": {
    "eks-mcp": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "mcp-proxy-for-aws@latest",
        "mcp-proxy-for-aws.exe",
        "https://eks-mcp.{region}.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "default",
        "--region",
        "{region}"
      ]
    }
  }
}

보안 참고: --read-only는 읽기 전용 도구 작업만 허용하도록 사용할 수 있습니다.

옵션 C: Cursor IDE

Cursor는 그래픽 구성 인터페이스와 함께 내장 MCP 지원을 제공합니다.

Cursor 설정 열기

Cursor 열기
Settings → Cursor Settings → Tools & MCP로 이동
또는 Cmd+Shift+P(Mac) / Ctrl+Shift+P(Windows)를 누르고 "MCP"를 검색

MCP 서버 구성 추가

**"New MCP Server"**를 클릭합니다.

파일이 없으면 만드세요. 리전({region}) 플레이스홀더를 원하는 리전으로 바꾸세요.

Mac/Linux:

{
  "mcpServers": {
    "eks-mcp": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://eks-mcp.{region}.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "default",
        "--region",
        "{region}"
      ]
    }
  }
}

Windows:

{
  "mcpServers": {
    "eks-mcp": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "mcp-proxy-for-aws@latest",
        "mcp-proxy-for-aws.exe",
        "https://eks-mcp.{region}.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "default",
        "--region",
        "{region}"
      ]
    }
  }
}

보안 참고: --read-only는 읽기 전용 도구 작업만 허용하도록 사용할 수 있습니다.

Cursor 재시작

변경 사항이 적용되도록 Cursor를 닫았다 다시 엽니다.

Cursor 채팅에서 확인

채팅 패널을 열고 시도해 보세요.

What EKS MCP tools are available?

사용 가능한 EKS 관리 도구 목록이 보여야 합니다.

옵션 D: Cline (VS Code Extension)

Cline은 AI 지원을 편집기에 직접 가져오는 널리 쓰이는 VS Code 확장입니다.

Cline 설정 열기

Cline 열기
Cmd+Shift+P(Mac) / Ctrl+Shift+P(Windows)를 누르고 "MCP"를 검색

MCP 서버 구성 추가

**"Add Server"**를 클릭합니다.

**"Open User Configuration"**을 클릭합니다.

파일이 없으면 만드세요. 리전({region}) 플레이스홀더를 원하는 리전으로 바꾸세요.

Mac/Linux:

{
  "mcpServers": {
    "eks-mcp": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://eks-mcp.{region}.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "default",
        "--region",
        "{region}"
      ]
    }
  }
}

Windows:

{
  "mcpServers": {
    "eks-mcp": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "mcp-proxy-for-aws@latest",
        "mcp-proxy-for-aws.exe",
        "https://eks-mcp.{region}.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "default",
        "--region",
        "{region}"
      ]
    }
  }
}

보안 참고: --read-only는 읽기 전용 도구 작업만 허용하도록 사용할 수 있습니다.

VS Code 다시 로드

Cmd+Shift+P / Ctrl+Shift+P를 누르고 "Developer: Reload Window"를 선택합니다.

구성 확인

Cline을 열고 물어보세요.

List the available MCP tools for EKS

2단계: (선택) "write" 정책 생성

선택적으로 Amazon EKS MCP 서버에 대한 전체 접근을 제공하는 고객 관리형 IAM 정책을 만들 수 있어요. 이 정책은 쓰기 작업을 포함할 수 있는 권한 있는 도구와 읽기 전용 도구를 모두 포함해 EKS MCP 서버의 모든 도구를 사용하는 권한을 부여합니다. 고위험 권한(Delete*가 포함된 것이나 제한 없는 IAM 리소스)은 manage_eks_stacks 도구에서 클러스터 리소스의 설정/해제에 필요하므로 이 정책에 포함되어 있어요.

aws iam create-policy \
 --policy-name EKSMcpWriteManagementPolicy \
 --policy-document "{...}" # 위 정책 문서 사용

3단계: 설정 확인

연결 테스트

연결을 확인하기 위해 AI 어시스턴트에게 간단한 질문을 하세요:

List all EKS clusters in my {aws} account

EKS 클러스터 목록이 보여야 합니다.

4단계: 첫 작업 실행

예제 1: 클러스터 탐색

Show me all EKS clusters and their status
What insights does EKS have about my production-cluster?
Show me the VPC configuration for my staging cluster

예제 2: Kubernetes 리소스 확인

Get the details of all the kubernetes resources deployed in my EKS cluster
Show me pods that are not in Running state or pods with any restarts
Get the logs from the aws-node daemonset in the last 30 minutes

예제 3: 문제 해결

Why is my nginx-ingress-controller pod failing to start?
Search the EKS troubleshooting guide for pod networking issues
Show me events related to the failed deployment in the staging namespace

예제 4: 리소스 생성 ("write" 모드가 활성화된 경우)

Create a new EKS cluster named demo-cluster with VPC and Auto Mode
Deploy my containerized app from ECR to the production namespace with 3 replicas
Generate a Kubernetes deployment YAML for my Node.js app running on port 3000

일반 구성 (Common configurations)

시나리오 1: 여러 AWS 프로필

여러 AWS 계정으로 작업한다면 별도의 MCP 서버 구성들을 만드세요.

Mac/Linux:

{
  "mcpServers": {
    "eks-mcp-prod": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://eks-mcp.us-west-2.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "production",
        "--region",
        "us-west-2"
      ]
    },
    "eks-mcp-dev": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://eks-mcp.us-east-1.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "development",
        "--region",
        "us-east-1"
      ]
    }
  }
}

Windows:

{
  "mcpServers": {
    "eks-mcp-prod": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "mcp-proxy-for-aws@latest",
        "mcp-proxy-for-aws.exe",
        "https://eks-mcp.us-west-2.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "production",
        "--region",
        "us-west-2"
      ]
    },
    "eks-mcp-dev": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "mcp-proxy-for-aws@latest",
        "mcp-proxy-for-aws.exe",
        "https://eks-mcp.us-east-1.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "development",
        "--region",
        "us-east-1"
      ]
    }
  }
}

시나리오 2: 프로덕션용 읽기 전용

프로덕션 환경용 읽기 전용 구성을 만듭니다.

Mac/Linux:

{
  "mcpServers": {
    "eks-mcp-prod-readonly": {
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://eks-mcp.us-west-2.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "production",
        "--region",
        "us-west-2",
        "--read-only"
      ],
      "autoApprove": [
        "list_k8s_resources",
        "get_pod_logs",
        "get_k8s_events"
      ]
    }
  }
}

Windows:

{
  "mcpServers": {
    "eks-mcp-prod-readonly": {
      "command": "uvx",
      "args": [
        "--from",
        "mcp-proxy-for-aws@latest",
        "mcp-proxy-for-aws.exe",
        "https://eks-mcp.us-west-2.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "production",
        "--region",
        "us-west-2",
        "--read-only"
      ],
      "autoApprove": [
        "list_k8s_resources",
        "get_pod_logs",
        "get_k8s_events"
      ]
    }
  }
}

시나리오 3: 전체 접근 개발

전체 쓰기 접근이 있는 개발 환경용.

Mac/Linux:

{
  "mcpServers": {
    "eks-mcp-dev-full": {
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://eks-mcp.us-east-1.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "development",
        "--region",
        "us-east-1"
      ]
    }
  }
}

Windows:

{
  "mcpServers": {
    "eks-mcp-dev-full": {
      "command": "uvx",
      "args": [
        "--from",
        "mcp-proxy-for-aws@latest",
        "mcp-proxy-for-aws.exe",
        "https://eks-mcp.us-east-1.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "development",
        "--region",
        "us-east-1"
      ]
    }
  }
}

고려 사항 (Considerations)

보안

허용된 입력 메커니즘을 통해 비밀 또는 민감한 정보를 전달하지 마세요.

apply_yaml로 적용하는 YAML 파일에 비밀 또는 자격 증명을 포함하지 마세요.
모델에 프롬프트로 직접 민감한 정보를 전달하지 마세요.
CloudFormation 템플릿이나 애플리케이션 매니페스트에 비밀을 포함하지 마세요.
Kubernetes Secrets를 만드는 데 MCP 도구를 사용하지 마세요. 이는 비밀 데이터를 모델에 제공해야 하기 때문입니다.
Kubernetes Pod 내부의 애플리케이션 로그에 민감한 정보를 기록하지 마세요.

YAML 콘텐츠 보안:

신뢰할 수 있는 출처의 YAML 파일만 사용하세요.
서버는 YAML 콘텐츠에 대해 Kubernetes API 검증에 의존하며 자체 검증을 수행하지 않습니다.
클러스터에 적용하기 전에 YAML 파일을 감사하세요.

MCP를 통해 비밀을 전달하는 대신:

민감한 정보를 저장하려면 AWS Secrets Manager 또는 Parameter Store를 사용하세요.
서비스 계정에 대해 적절한 Kubernetes RBAC를 구성하세요.
Pod에서 AWS 서비스 접근을 위해 서비스 계정용 IAM 역할 (IRSA)을 사용하세요.

민감한 데이터 편집:

EKS MCP Server는 도구 응답에서 보안 토큰, 인증서, 기타 민감한 정보의 일반적인 패턴을 자동으로 편집합니다.
편집된 값은 모델에 우연히 데이터가 노출되지 않도록 HIDDEN_FOR_SECURITY_REASONS로 대체됩니다.
이 편집은 로그, 리소스 설명, 구성 데이터를 포함한 모든 도구 응답에 적용됩니다.

다음 단계 (Next up)

구성 옵션은 Amazon EKS MCP Server Configuration Reference를, 전체 도구 목록은 Amazon EKS MCP Server Tools Reference를 참고하세요.

더 알아보기 (Learn more)

출처: 문서