Amazon Q MCP 설정 방법 — Q Developer에 MCP 서버 연결하는 전체 흐름
Amazon Q Developer CLI·IDE에서 MCP 서버를 연결하는 방법을 단계별로 완전 정리했습니다. mcp.json 설정부터 Q CLI MCP 연동, AWS MCP 연결 오류 해결까지 한 번에 해결합니다.
Amazon Q Developer CLI에 MCP 서버를 연결하면 ~/.aws/amazonq/mcp.json 파일 하나만 편집해 원하는 도구를 Q의 대화 흐름에 바로 추가할 수 있습니다. Claude Desktop과 설정 구조가 거의 같아서, 기존 MCP 서버 설정을 그대로 재활용할 수 있습니다. 이 가이드에서는 Q CLI와 IDE 플러그인 양쪽에서 MCP 서버를 연결하는 전체 흐름, 흔한 오류와 해결법, 실제 유용한 서버 예시까지 단계별로 설명합니다.
Amazon Q Developer에서 MCP가 필요한 이유
Amazon Q Developer는 AWS가 제공하는 AI 코딩 어시스턴트입니다. 기본 제공 기능만으로도 코드 생성, 버그 수정, 문서 작성에 유용하지만, MCP(Model Context Protocol) 를 연결하면 Q가 직접 외부 도구를 호출할 수 있게 됩니다. 예를 들어 HWP 문서를 Markdown으로 변환하거나, 사내 API 결과를 Q가 읽어 코드 리뷰에 반영하는 식의 워크플로가 가능해집니다.
[개발자 자연어 요청]
↓
[Amazon Q Developer (AI)]
↓ MCP 프로토콜 (stdio)
[로컬 MCP 서버 프로세스]
↓ API 호출 / 파일 처리
[외부 서비스 / 로컬 파일]
↓ 결과 반환
[Q → 결과를 문맥에 포함해 응답]
MCP 서버는 Q와 별개의 로컬 프로세스로 실행됩니다. Q가 대화 중 도구 호출이 필요하다고 판단하면 stdio 채널을 통해 MCP 서버에 요청을 보내고, 서버가 처리 결과를 돌려줍니다.
준비물
| 항목 | 설명 |
|---|---|
| Amazon Q Developer CLI | q 명령 사용 가능해야 함 (AWS 공식 문서 참고) |
| Node.js v18 이상 | npx 기반 MCP 서버 실행 시 필요 |
| Python + uv (선택) | uvx 기반 Python MCP 서버 실행 시 필요 |
| 연결할 MCP 서버 | npx 또는 uvx로 실행 가능한 서버 |
Amazon Q CLI에서 MCP 서버 설정하기 (단계별)
1단계. Q CLI 설치 확인
터미널에서 아래 명령을 실행해 Q CLI가 설치되어 있는지 확인합니다.
q --version
버전 정보가 출력되면 정상입니다. 설치되어 있지 않다면 AWS 공식 문서의 Amazon Q Developer CLI 설치 안내를 먼저 따릅니다.
2단계. mcp.json 파일 위치 확인 및 생성
Q CLI는 MCP 서버 목록을 ~/.aws/amazonq/mcp.json 파일에서 읽습니다.
# 디렉토리가 없으면 생성
mkdir -p ~/.aws/amazonq
# 파일 존재 여부 확인
ls ~/.aws/amazonq/mcp.json
파일이 없으면 아래처럼 새로 생성합니다. 파일이 이미 있다면 기존 내용을 유지하면서 mcpServers 블록에 서버를 추가합니다.
3단계. mcp.json에 MCP 서버 추가
아래는 mcp.json의 기본 구조입니다. mcpServers 키 안에 원하는 서버를 이름으로 구분해 넣습니다.
{
"mcpServers": {
"서버이름": {
"command": "npx",
"args": ["-y", "패키지명"],
"env": {
"환경변수명": "값"
}
}
}
}
실제 예시: 코르독(KorDoc) 서버 추가
한국 공문서(HWP·PDF·DOCX 등)를 Markdown으로 변환해 Q에게 전달하는 코르독(KorDoc) 서버를 추가하는 예시입니다.
{
"mcpServers": {
"kordoc": {
"command": "npx",
"args": ["-y", "kordoc", "mcp"],
"env": {}
}
}
}
설치 명령 npx -y kordoc setup을 그대로 반영한 것입니다. env가 필요 없는 서버는 빈 객체로 두거나 키를 생략해도 됩니다.
여러 서버를 동시에 추가하는 예시
{
"mcpServers": {
"kordoc": {
"command": "npx",
"args": ["-y", "kordoc", "mcp"]
},
"hwp-mcp": {
"command": "npx",
"args": ["-y", "hwp-mcp"]
},
"hwpforge": {
"command": "npx",
"args": ["-y", "@hwpforge/mcp"]
}
}
}
위 예시는 한글 문서 처리 MCP 서버 세 가지를 동시에 등록하는 설정입니다. 각 서버는 독립 프로세스로 실행됩니다.
4단계. Q CLI 재시작 및 연결 확인
이미 q chat이 실행 중이라면 종료 후 다시 시작합니다.
q chat
대화 창이 열리면 아래 명령으로 등록된 MCP 도구를 확인합니다.
/tools
등록한 서버가 정상적으로 연결됐다면, 서버가 제공하는 도구 이름이 목록에 나타납니다.
5단계. 도구 호출 테스트
자연어로 MCP 서버의 기능을 요청해 봅니다.
이 폴더에 있는 report.hwp 파일을 읽어서 핵심 내용을 요약해 줘.
Q가 MCP 서버를 호출하는 경우, 어떤 도구를 사용할지 물어보거나 자동으로 호출합니다. 결과가 정상으로 반환되면 설정이 완료된 것입니다.
IDE 플러그인(VS Code·JetBrains)에서 MCP 설정하기
IDE용 Amazon Q 플러그인은 CLI와 설정 파일을 공유하지 않습니다. 플러그인 설정 화면에서 별도로 MCP 서버를 추가해야 합니다.
| 환경 | 설정 방법 |
|---|---|
| Q CLI (터미널) | ~/.aws/amazonq/mcp.json 파일 직접 편집 |
| VS Code Q 플러그인 | 플러그인 설정 UI 또는 .amazonq/mcp.json (워크스페이스) |
| JetBrains Q 플러그인 | IDE 설정 패널 내 MCP 서버 항목 추가 |
플러그인 버전에 따라 인터페이스가 다를 수 있으므로, 정확한 경로는 Amazon Q Developer 공식 문서를 참고하세요.
흔한 오류와 해결 방법
오류: q chat 시작 후 /tools 목록이 비어 있음
가장 흔한 원인은 JSON 문법 오류입니다. 콤마, 괄호, 따옴표를 확인하세요.
# JSON 문법 검사
cat ~/.aws/amazonq/mcp.json | python3 -m json.tool
출력 없이 종료되면 JSON이 정상입니다. 오류 메시지가 나오면 해당 줄을 수정합니다.
오류: command not found (npx 또는 uvx)
# Node.js 설치 확인
node --version
npx --version
# Python uv 설치 확인 (uvx 기반 서버)
uv --version
npx가 없으면 Node.js를, uv가 없으면 https://docs.astral.sh/uv 를 참고해 설치합니다.
오류: 특정 서버만 목록에 없음
해당 서버의 command와 args를 터미널에서 직접 실행해 오류 메시지를 확인합니다.
# kordoc 직접 실행 테스트
npx -y kordoc mcp
패키지를 찾을 수 없거나 실행 오류가 발생하면 패키지 이름과 버전을 확인합니다.
오류: 환경 변수가 전달되지 않음
env 블록의 값에 공백이나 줄 바꿈이 섞이면 인식이 안 될 수 있습니다. API 키처럼 민감한 값은 직접 입력하지 않고 쉘의 환경 변수를 참조하는 방법도 있으나, mcp.json은 현재 쉘 변수 치환을 직접 지원하지 않으므로 값을 문자열로 직접 입력해야 합니다.
관련 MCP 서버: 한글 문서 처리 3종
Amazon Q와 함께 쓸 수 있는 한국산 MCP 서버 중 한글 문서 처리 서버 세 가지를 소개합니다.
| 서버 | 기능 | 설치 명령 | GitHub |
|---|---|---|---|
| 코르독(KorDoc) | HWP·PDF·XLSX·DOCX → Markdown 변환 | npx -y kordoc setup | github.com/chrisryugj/kordoc |
| HWP-MCP | .hwp/.hwpx 읽기·편집·생성 | npx -y hwp-mcp | github.com/treesoop/hwp-mcp |
| 한포지(HwpForge) | HWPX 읽기·쓰기·변환 (KS X 6101) | npx -y @hwpforge/mcp | github.com/ai-screams/HwpForge |
세 서버 모두 API 키가 필요 없으며 npx로 바로 실행할 수 있습니다. 한글 문서를 다루는 업무가 많다면 개발 도구 카테고리의 다른 서버들도 함께 살펴보세요.
다음 단계
Amazon Q Developer에 MCP 서버를 연결했다면, 다음 단계로는 워크스페이스별 설정을 분리하거나 팀 단위로 공유하는 방법을 검토해 볼 수 있습니다. 프로젝트 루트의 .amazonq/mcp.json에 설정을 두면 해당 프로젝트 안에서만 적용되므로 팀원과 함께 버전 관리가 가능합니다. 한국 개발자를 위한 다양한 MCP 서버 목록은 전체 서버 목록에서 확인하고, 새로운 서버를 발견했다면 가이드 목록에서 더 많은 활용법을 찾아보세요.
자주 묻는 질문
Amazon Q Developer에서 MCP 설정 파일은 어디에 있나요?
Q CLI(터미널)는 ~/.aws/amazonq/mcp.json을 읽습니다. IDE 플러그인(VS Code, JetBrains)은 플러그인 설정 화면에서 별도로 MCP 서버를 추가해야 합니다. 두 환경의 설정은 공유되지 않습니다.
Claude Desktop의 claude_desktop_config.json 설정을 그대로 복사해도 되나요?
구조는 거의 같습니다. mcpServers 키 아래의 서버 정의(command, args, env)는 동일하게 사용할 수 있습니다. 단, 파일 경로와 파일명이 다르므로 Q CLI용 경로(~/.aws/amazonq/mcp.json)에 저장해야 합니다.
Q CLI에서 MCP 서버가 목록에 안 나타납니다. 어떻게 확인하나요?
q chat을 새로 실행한 뒤 /tools를 입력하면 연결된 도구 목록이 표시됩니다. 목록이 없다면 mcp.json 파일의 JSON 문법 오류나 command 경로 문제를 먼저 확인하세요.
npx 기반 MCP 서버와 uvx 기반 서버를 Q CLI에서 동시에 쓸 수 있나요?
네, 가능합니다. mcpServers 블록 안에 여러 서버를 함께 정의하면 됩니다. 각 서버는 독립 프로세스로 실행되므로 Node.js 기반(npx)과 Python 기반(uvx) 서버를 동시에 사용해도 충돌이 없습니다.
AWS IAM 자격증명이 없어도 로컬 MCP 서버를 Q CLI에서 실행할 수 있나요?
네. MCP 서버 자체가 AWS API를 호출하지 않는다면 IAM 자격증명 없이도 실행됩니다. AWS 서비스와 직접 연동하는 서버(예: S3, DynamoDB 접근)는 별도의 자격증명이 필요합니다.
Amazon Q Developer 무료 티어에서도 MCP 서버를 사용할 수 있나요?
Amazon Q Developer의 MCP 지원 여부와 플랜별 제한은 AWS 공식 문서에서 최신 정보를 확인하세요. 기능 제공 범위는 업데이트될 수 있습니다.