4. Q CLI 기반 MCP 구성하기 1

Update : 2025.06.03

Amazon Q Developer CLI: Model Context Protocol(MCP) 활용

1. 개요

Model Context Protocol (MCP)는 LLM이 다양한 도구 및 시스템과 통합되도록 해주는 표준 인터페이스입니다. 마치 USB-C가 다양한 장치 간 연결을 통합하듯, MCP는 LLM이 외부 도구 및 데이터를 표준 방식으로 활용할 수 있게 해줍니다.

Amazon Q Developer CLI는 현재 MCP를 베타로 지원하며, Kubernetes API 및 Playwright 기반 브라우저 제어를 예제로 소개합니다.

준비 조건

/quit  # 기존 세션 종료
#python3.11 설치
sudo dnf install python3.11 python3.11-pip python3.11-devel -y
# uv 설치
curl -LsSf https://astral.sh/uv/install.sh | sh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
# nodejs 설치
sudo dnf install -y nodejs20  # MCP 서버 실행을 위한 Node.js 설치

amazon q cli는 기본 agent가 q_cli_default로 설정되어 있습니다.

q_cli_default는 ~/.amazonq/rules/**/*.md 또는 chat session이 활성화 되는 디렉토리의 README.md , AmazonQ.md 의 Context를 호출해서 사용합니다.

아래와 같이 q_cli_default agent를 위한 context를 생성합니다.

mkdir ~/.amazonq/
mkdir ~/.amazonq/rules
mkdir ~/.amazonq/rules/qclidefault
cat > ~/.amazonq/rules/qclidefault/AmazonQ.md << 'EOF'
기본리전은 ap-northeast-2 입니다.
EKS Cluster Name은 eksworkshop 입니다.
모든 응답은 한국어로 답하고, 기술용어는 한국어와 영어를 병기합니다.
최종 결과는 markdown으로 만들고, ~/output 디렉토리에 파일로 작성합니다.
EOF

---

2. MCP 서버 구성

Amazon Q Developer CLI는 kubectl 없이도 Kubernetes API에 직접 접근할 수 있도록 지원합니다. 이 기능은 MCP 서버를 통해 활성화되며, 실시간으로 클러스터 상태를 파악하거나 명령을 실행할 수 있는 기반이 됩니다.

MCP 서버란?

MCP(Model Context Protocol)는 LLM이 외부 시스템과 표준화된 방식으로 상호작용할 수 있도록 해주는 오픈 프로토콜입니다.

Amazon Q CLI에서는 ~/.aws/amazonq/mcp.json 파일을 통해 MCP 서버를 설정합니다.

# MCP Server 설정
~/.aws/amazonq/mcp.json 

2.1 설정 단계

• MCP 구성 파일 열기

terminal 에서 아래와 같이 실행합니다.

• mcp.json 파일 생성

cat > ~/.aws/amazonq/mcp.json << 'EOF'
{
  "mcpServers": {
    "awslabs.eks-mcp-server": {
      "command": "uvx",
      "args": [
        "awslabs.eks-mcp-server@latest",
        "--allow-write",
        "--allow-sensitive-data-access"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "autoApprove": [],
      "disabled": false
    }
  }
}
EOF

aws mcp 공식 사이트에서 다양한 AWS 자원을 위한 MCP를 확인 할 수 있습니다. (https://awslabs.github.io/mcp/)

• Q CLI 재시작 및 MCP 적용 확인

cd ~/.amazonq/rules/qclidefault
q chat

결과 예시:

$ q chat
To learn more about MCP safety, see https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-security.html
✓ kubernetes loaded in 8.00 s
✓ 1 of 1 mcp servers initialized

Welcome to 

 █████╗ ███╗   ███╗ █████╗ ███████╗ ██████╗ ███╗   ██╗     ██████╗ 
██╔══██╗████╗ ████║██╔══██╗╚══███╔╝██╔═══██╗████╗  ██║    ██╔═══██╗
███████║██╔████╔██║███████║  ███╔╝ ██║   ██║██╔██╗ ██║    ██║   ██║
██╔══██║██║╚██╔╝██║██╔══██║ ███╔╝  ██║   ██║██║╚██╗██║    ██║▄▄ ██║
██║  ██║██║ ╚═╝ ██║██║  ██║███████╗╚██████╔╝██║ ╚████║    ╚██████╔╝
╚═╝  ╚═╝╚═╝     ╚═╝╚═╝  ╚═╝╚══════╝ ╚═════╝ ╚═╝  ╚═══╝     ╚══▀▀═╝ 
                                                        


╭───────────────────────── Did you know? ─────────────────────────╮
│                                                                 │
│      You can execute bash commands by typing ! followed by      │
│                           the command                           │
│                                                                 │
╰─────────────────────────────────────────────────────────────────╯


/help all commands  •  ctrl + j new lines  •  ctrl + k fuzzy search
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

All tools are now trusted (!). Amazon Q will execute tools without asking for confirmation.
Agents can sometimes do unexpected things so understand the risks.

Learn more at https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-chat-security.html#command-line-chat-trustall-safety

2.2 MCP 기반 호출

프롬프트:

kube-system 네임스페이스에서 실행 중인 파드들은 무엇인가요?
결과는 표 형태로 출력하고, 각 구성 요소가 무엇인지 설명도 함께 제공해 주세요.

결과 예시:

kube-system 네임스페이스의 파드 분석이 완료되었습니다! 

## 주요 결과 요약

총 42개의 파드가 6가지 주요 구성 요소로 실행되고 있습니다:

| 구성 요소 | 파드 수 | 역할 |
|----------|--------|------|
| aws-node | 12개 | VPC CNI 네트워킹 |
| coredns | 2개 | DNS 서비스 |
| ebs-csi-controller | 2개 | EBS 볼륨 관리 |
| ebs-csi-node | 12개 | 노드별 볼륨 드라이버 |
| kube-proxy | 12개 | 네트워크 프록시 |
| metrics-server | 2개 | 리소스 메트릭 수집 |

모든 파드가 Running 상태로 정상 동작하고 있으며, 12개의 워커 노드를 가진 안정적인 EKS 클러스터임을 확인할 수 있습니다.

상세한 분석 결과는 ~/output/kube-system-pods-analysis.md 파일에 저장되었습니다. 각 구성 요소의 역할과 기능에 대한 자세한 설명이 포함되어 있습니다.

• Markdown 결과 예시

MCP로 추가된 도구들은 아래와 명령을 통해서 확인 할 수 있습니다.

/tools

출력 예시에는 MCP 서버를 통해 추가된 kubernetes___ prefix를 가진 도구들이 포함되어 있습니다:

/tools


Tool                               Permission
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔Built-in:
- execute_bash                     * trusted
- fs_read                          * trusted
- fs_write                         * trusted
- report_issue                     * trusted
- use_aws                          * trusted

awslabs.eks-mcp-server (MCP):
- add_inline_policy                * not trusted
- apply_yaml                       * not trusted
- generate_app_manifest            * not trusted
- get_cloudwatch_logs              * not trusted
- get_cloudwatch_metrics           * not trusted
- get_eks_metrics_guidance         * not trusted
- get_k8s_events                   * not trusted
- get_pod_logs                     * not trusted
- get_policies_for_role            * not trusted
- list_api_versions                * not trusted
- list_k8s_resources               * trusted
- manage_eks_stacks                * not trusted
- manage_k8s_resource              * not trusted
- search_eks_troubleshoot_guide    * not trusted

3.요약

항목	설명
도구 설치 여부	kubectl 설치 없이 Kubernetes API 직접 접근 가능
도구 위치	~/.aws/amazonq/mcp.json
작동 방식	MCP 서버가 백그라운드에서 API 요청 처리
장점	LLM 기반 CLI의 실시간 클러스터 질문 응답 기능 강화