DB & AWS Knowledge
Amazon Q CLI 를 자신의 Aurora Cluster 에 연결하기 (MCP) 본문
Amazon Q CLI 를 자신의 Aurora Cluster 에 연결하기 (MCP)
`O` 2025. 7. 2. 02:09이 페이지에서는 Amazon Q CLI 를 자신의 Aurora Cluster DB 에 MCP 개념으로 연결하는 과정을 기재한다.
이 페이지는 perplexity pro 를 통하여 확인 한 가이드 사항에 사용자가 더 이해하기 쉽게 추가 내용을 기재한다.
또한, 검색이외에 추가로 덧붙일 내용은 ※ 로 추가한다.
(Perplexity 가 아니더라도 자신이 사용하는 AI 솔루션을 유료 버전으로 사용한다면 설치 안내 과정은 비슷하게 안내 될 것이다.)
이 가이드는 Amazon Linux 2023 를 기준으로 설명된다.
또한 필자가 AI 를 통하여 만든 가이드 또한 아래에 첨부한다. 이 가이드에 있는 명령어를 복사하여 Amazon Q CLI 를 구성 할 수 있다.
Amazon Q CLI 설치 과정
- 먼저 Amazon Q Cli 를 설치하기 위해서는 확인 해야 할 사항이있다.
먼저, 아래와 같이 glibc 패키지가 설치되어 있는지 확인한다.
또한 glibc 2.34 이상인지 확인한다. 2.34 미만이면 musl 버전을 사용해야 한다.
$ ldd --version
ldd (GNU libc) 2.34
Copyright (C) 2021 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Written by Roland McGrath and Ulrich Drepper.
[ec2-user@ip-10-0-1-202 ~]$ sudo dnf update
Last metadata expiration check: 6:59:59 ago on Tue Jul 1 06:35:04 2025.
- 그 다음 curl 과 unzip 이 설치되어 있는지 확인 후 필요시 설치한다.
$sudo dnf update
Last metadata expiration check: 6:59:59 ago on Tue Jul 1 06:35:04 2025.
Dependencies resolved.
==================================================================================================================================
Package Architecture Version Repository Size
==================================================================================================================================
Upgrading:
amazon-linux-repo-s3 noarch 2023.7.20250623-0.amzn2023 amazonlinux 16 k
awscli-2 noarch 2.25.0-1.amzn2023.0.1 amazonlinux 12 M
kernel-libbpf x86_64 6.12.31-35.92.amzn2023 amazonlinux 186 k
kernel-livepatch-repo-s3 noarch 2023.7.20250623-0.amzn2023 amazonlinux 16 k
kernel-tools x86_64 6.12.31-35.92.amzn2023 amazonlinux 174 k
(...)
$ sudo dnf install curl unzip -y
Last metadata expiration check: 7:00:36 ago on Tue Jul 1 06:35:04 2025.
Package unzip-6.0-57.amzn2023.0.2.x86_64 is already installed.
Error:
Problem: problem with installed package curl-minimal-8.11.1-4.amzn2023.0.1.x86_64
(...)
# 필자의 EC2 에는 이미 amzn2023 curl 이 설치되어 있어서 curl 설치시 충돌이 일어나기에 필자의 테스트 환경에서는 이를 생략한다.
- 위와 같이 필요 패키지 및 프로그램을 설치했다면, 아래의 명령어를 그대로 사용하여 Amazon Q zip 을 다운로드 받을 디렉토리에 다운로드 한다.
curl --proto '=https' --tlsv1.2 -sSf "https://desktop-release.q.us-east-1.amazonaws.com/latest/q-x86_64-linux.zip" -o "q.zip"
#위의 사항은 Amazon Linux 2023 (x86_64 아키텍처) 에서만 사용가능한 명령어다. 만일 자신의 EC2 또는 OS 환경이 ARM (aarch64) 이면 아래의 명령어를 사용한다.
curl --proto '=https' --tlsv1.2 -sSf "https://desktop-release.q.us-east-1.amazonaws.com/latest/q-aarch64-linux.zip" -o "q.zip"
- 그 후, unzip 으로 압축을 푼 후, 설치를 한다.
$ unzip q.zip
Archive: q.zip
creating: q/
inflating: q/install.sh
inflating: q/README
inflating: q/BUILD-INFO
creating: q/bin/
inflating: q/bin/q
inflating: q/bin/qterm
inflating: q/bin/qchat
# 아래의 install 을 하면 AI 가 shell config 를 변경하도록 허용 할 지, login 은 어떤 계정을 사용할지 선택한다. 이 때, Amazon Q 를 pro 로 사용하는 사용자라면 pro 를 선택한다.
$ ./q/install.sh
✔ Do you want q to modify your shell config (you will have to manually do this otherwise)? · Yes
? Select login method ›
❯ Use for Free with Builder ID
Use with Pro license
(...)
- 위의 설정이 완료되면 아래와 같이 브라우저에서 사용하는 Amazon ID 를 login 하도록 요청받는다.
안내 받은 링크를 통해 Amazon.com 로그인과 같이 로그인 하면 된다.
Confirm the following code in the browser
Code: SDWN-QSTK
Open this URL: https://view.awsapps.com/start/#/device?user_code=SDWN-QSTK
- 로그인이 정상적으로 되면 아래와 같이 Amazon Q 가 자신의 데이터가 접근하도록 허용한다.
- 접속허용까지 되면 아래와 같이 설치가 완료된다.
Confirm the following code in the browser
Code: SDWN-QSTK
Open this URL: https://view.awsapps.com/start/#/device?user_code=SDWN-QSTK
Device authorized
Logged in successfully
#만일 이후에 login 을 다시 해야 하는 경우에는 아래의 명령어를 입력하면 된다.
(필자의 테스트 환경에서 이를 입력시 어떤 결과가 나오는지 미리 확인)
$q login
error: Already logged in, please logout with q logout first
- 그다음 Amazon Q 가 사용할 프로젝트 디렉토리를 만든다.
# 전역 설정 디렉토리 생성
mkdir -p ~/.aws/amazonq
# 또는 워크스페이스 설정 디렉토리 생성
mkdir -p .amazonq
- 이제 필자가 사용하는 Aurora MySQL Cluster 에 Amazon Q CLI 를 연동시키기 위해서 아래와 같이 ~/.aws/amazonq/mcp.json 파일을 만들고 아래의 내용을 기재한다. 여기서 사용자가 준비 해야 할 사항은 아래와 같다.
- 연동시킬 Aurora Cluster
- Secret Manager 정보 (현재 Amazon Q 는 Aurora Cluster 등의 DB 접근시, 보안을 위하여 Secret Manager 를 통해서만 접속이 가능하다. 만일 기존에 user, PW 의 단순 login 을 사용했다면 관리자 계정을 기준으로 하는 Secret Manager 정보를 하나 만들고, 이를 Cluster 에 반영하도록 Cluster 를 수정 (Modify) 하면 된다. ARN 또한 Secret Manager 에서 확인 가능하다.)
- AWS Profile (필자는 default 로 사용하나, 이는 사용자마다 회사 규정등으로 인하여 정해진 profile 을 쓸 수 있다. 이에 맞춰쓴다.)
$ vi ~/.aws/amazonq/mcp.json
{
"mcpServers": {
"awslabs.mysql-mcp-server": {
"command": "uvx",
"args": [
"awslabs.mysql-mcp-server@latest",
"--resource_arn", "arn:aws:rds:ap-northeast-2:(계정):db:(CLuster 명)",
"--secret_arn", "arn:aws:secretsmanager:ap-northeast-2:(계정):secret:rds!cluster-b67dae33-bd0c-4cf7-8751-7b0099dde66d-ClYBVr",
"--database", "test",
"--region", "ap-northeast-2",
"--readonly", "False"
],
"env": {
"AWS_PROFILE": "default",
"AWS_REGION": "ap-northeast-2",
"FASTMCP_LOG_LEVEL": "ERROR"
},
"disabled": false,
"autoApprove": []
}
}
}
- 만일 PostgreSQL 에 접속시에는 아래의 포맷을 사용하면 된다.
{
"mcpServers": {
"awslabs.postgres-mcp-server": {
"command": "uvx",
"args": [
"awslabs.postgres-mcp-server@latest",
"--resource_arn", "arn:aws:rds:us-east-1:123456789012:cluster:your-cluster-name",
"--secret_arn", "arn:aws:secretsmanager:us-east-1:123456789012:secret:your-secret-name",
"--database", "your-database-name",
"--region", "us-east-1",
"--readonly", "True"
],
"env": {
"AWS_PROFILE": "your-aws-profile",
"AWS_REGION": "us-east-1",
"FASTMCP_LOG_LEVEL": "ERROR"
},
"disabled": false,
"autoApprove": []
}
}
}
- 그 후, Amazon CLI 가 정상적으로 실행되도록 마지막으로 python 및 종속 패키지 설치 확인을 한다.
# Python 3.10 이상 설치 확인
python3 --version
# uv 설치 (Python 패키지 관리자)
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc
- 그 후, Amazon Q CLI 의 설치확인을 한다. Amazon Q 가 정상적으로 설치되었다면 CLI 또한 설치 되었을 가능성이 높으나 만일을 위하여 최종확인을 한다.
$sudo dnf install awscli -y
Last metadata expiration check: 7:27:44 ago on Tue Jul 1 06:35:04 2025.
Package awscli-2-2.25.0-1.amzn2023.0.1.noarch is already installed.
Dependencies resolved.
Nothing to do.
Complete!
- 이제 Amazon Q CLI 가 RDS, Aurora Cluster 에 사용할 Data API 및 Secret Manager 를 사용하려면 아래와 같이 IAM 권한을 추가 해 줘야한다. 필자는 이를 신규 Policy 로 만들어서 사용중인 role 에 넣었다.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"rds-data:ExecuteStatement",
"rds-data:BatchExecuteStatement",
"rds-data:BeginTransaction",
"rds-data:CommitTransaction",
"rds-data:RollbackTransaction"
],
"Resource": "arn:aws:rds:*:*:cluster:your-cluster-name"
},
{
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue",
"secretsmanager:DescribeSecret"
],
"Resource": "arn:aws:secretsmanager:*:*:secret:your-secret-name"
}
]
}
- 그다음 아래 CLI 를 통하여 Aurora Cluster 에 사용할 Data API 를 활성화 시킨다.
# Aurora 클러스터의 Data API 활성화 (결과가 나오는지 까지 확인 필요)
$ aws rds modify-db-cluster \
--db-cluster-identifier support-rds-aurora-mysql-test \
--enable-http-endpoint \
--region ap-northeast-2
{
"DBCluster": {
"AllocatedStorage": 1,
"AvailabilityZones": [
"ap-northeast-2b",
"ap-northeast-2a",
"ap-northeast-2d"
(...)
- 여기까지가 설치과정이며, 이후에는 Amazon Q CLI 가 정상적으로 실행되는지 테스트 해 보면된다.
$q
# Amazon Q 접속 후, tool 확인
/tools
Amazon Q 에서는 영어가 기본 제공 언어이지만 AI 특성상 한국어도 인식한다.
> 한국어 인식
> I can recognize and understand Korean text. You wrote "한국어 인식" which means "Korean recognition" or "Korean language
recognition."
I'm able to communicate in Korean if you'd prefer to continue our conversation in Korean, or I can help you with any Korean-
related tasks you might have. What would you like assistance with?
- 이제 우리가 위의 JSON 파일을 통해 인식시킨 Cluster 에 Amazon Q 가 접속하는지 확인 해 보자. 아래의 프롬프트를 작성하면 된다. (보안을 위해 필자의 cluster 명은 가렸다.)
- 위와 같이 Amazon Q 가 접속이 가능해 지면 DB 작업 등도 요청 할 수 있다. 이 때, 아래에 보면 Amazon Q 가 DB 작업을 수행하도록 허용 하도록 한번 더 묻는데. 여기서 필자는 Amazon Q 가 계속 이후에도 작업을 하도록 t (trust) 로 설정했다.
- 이후에 MCP 의 장점을 기술하겠지만, MCP 는 아래와 같이 사용자 환경에 맞춰 공개 AI 솔루션의 답변이외에 자체적인 조치도 취할 수있다. 예를 들어 필자가 사용하는 Amazon Linux 에는 MySQL Client 가 설치되어 있지 않아 실제 DB 작업을 할 수 없었지만, Amazon Q 에게 특정 작업을 요청하면서 Amazon Q 가 이를 확인 필요한 조치도 알아서 취할 수 있다.
(중간 생략)
이와 같이 사용자가 SQL 및 명령어등을 직접 작성하지 않아도 Amazon Q CLI MCP 가 사용자의 환경에 맞춘 답변을 내놓 도록 할 수 있다.
'AWS 및 클라우드 지식 > DB 이외 AWS 서비스, 클라우드 지식' 카테고리의 다른 글
| On premise 3 tier 를 AWS 환경으로 전환할 시, 이용되는 서비스 (0) | 2025.06.05 |
|---|---|
| DocumentDB 개요 및 특징 (0) | 2025.04.30 |
| CloudWatch 의 Log Insight 기능 사용방법과 의의 (0) | 2024.08.28 |
| 구입한 Reserved Instance (RI) 에 대한 취소 과정 (0) | 2024.08.27 |
| CloudWatch 를 통해 Custom Metric 만들기 (0) | 2024.08.23 |