[AWS Amazon Q] Amazon Q Developer CLI과 Local MCP 서버를 연결하여 사용해보기

1. Amazon Q Developer CLI 설치하기(MacOS)

설치 후 Amazon Q 앱을 실행하여 Shell Ingtegration을 수행해야 터미널에서 명령어 실행이 가능합니다.

brew install amazon-q
# 설치 후 [Amazon Q]앱을 실행하여 Shell Integration을 진행해야 다음 명령어 수행이 가능합니다.
q --version

x

2. Amazon Q Developer Chat

Amazon Q Developer CLI는 터미널에서 대화형 채팅 환경을 제공합니다. 명령줄 환경을 벗어나지 않고도 질문하고, AWS 서비스에 대한 도움을 받고, 문제를 해결하고, 코드를 생성할 수 있습니다. Amazon Q로 채팅 세션을 시작하려면 chat 명령을 사용합니다.

q chat

 

3. Amazon Q Developer CLI 실행

uv 는 Python 패키지 설치 및 가상 환경 관리를 위한 도구입니다. 터미널에서 다음 명령어를 실행하여 설치합니다.

# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh

# 설치 완료 확인
uv --version

4. Local 환경에 Weather API MCP 서버 만들기

4-1) 샘플 코드 다운로드

git clone https://github.com/aws-samples/aws-kr-startup-samples.git
cd aws-kr-startup-samples/gen-ai/mcp-tutorial/module-01/part-01/src/example-1

4-1) Python 가상 환경 설정 및 필요 패키지 설치

uv venv
source .venv/bin/activate
uv add "mcp[cli]" httpx

4-1) Python 가상 환경 설정 및 필요 패키지 설치

cat weather.py

이 스크립트는 미국 국립 기상 서비스 API를 통해 날씨 정보를 가져오는 MCP 서버를 구현합니다. 사용자의 프롬프트로부터 날씨를 받을 때, get_alerts, get_forecast 를 활용하여 위도와 경보를 파악하고 기상 정보를 가져오도록 동작합니다.

5. Amazon Q Developer CLI MCP Server 호출 구성

Global Configuration 구성으로 실습을 진행합니다. ~/.aws/amazonq/mcp.json 파일을 아래처럼 수정합니다.

[주의] ~/ABSOLUTE/PATH/TO : 다운로드 받은 코드의 절대 경로로 변경해주세요.

{
    "mcpServers": {
        "weather": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/aws-kr-startup-samples/gen-ai/mcp-tutorial/module-01/part-01/src/example-1",
                "run",
                "weather.py"
            ]
        }
    }
}

 

6. MCP 서버가 정상적으로 등록 되었는지 확인

# Amazon Q CLI 실행
q chat

# 연결된 로컬 MCP 서버 확인
/tools

7. 등록된 Local MCP Server으로 질의/응답 확인

Amazon Q Developer CLI를 재실행하고, What are the active weather alerts in Texas? 와 같은 질문을 입력하여 응답을 확인합니다. Allow this action? Use 't' to trust (always allow) this tool for the session. [y/n/t]: 입력창이 나타나면,  t 를 입력합니다.

8. 참고

https://docs.aws.amazon.com/ko_kr/amazonq/latest/qdeveloper-ug/command-line-mcp.html