이 페이지는 AI의 도움을 받아 영어에서 번역되었습니다. 두 내용이 다를 경우 영어 버전을 기준으로 합니다.
Claude Desktop에서 StackQL 사용
StackQL은 Model Context Protocol(MCP)를 통해 Claude Desktop과 통합되므로 자연어를 사용하여 여러 클라우드 제공업체의 클라우드 리소스를 쿼리하고 프로비저닝할 수 있습니다. 이 강력한 조합을 통해 내부적으로는 StackQL의 SQL 기반 인터페이스를 활용하면서 대화 방식으로 클라우드 인프라와 상호 작용할 수 있습니다.
설치 옵션은 3가지이며 여기서는 권장 순서대로 제시합니다: Anthropic Connector Directory에서 설치, 다운로드한 번들에서 설치, 로컬에 설치된 StackQL 바이너리를 수동으로 등록.
Connector Directory에서 설치(권장)
Claude Desktop에서 StackQL MCP 서버를 사용하는 가장 쉬운 방법은 Anthropic Connector Directory에서 설치하는 것입니다. Claude Desktop에서 Settings -> Connectors -> Add -> Browse Connectors로 이동하여 StackQL을 검색하고 Install을 클릭합니다. 다운로드할 것이 없으며 StackQL을 별도로 설치할 필요도 없습니다.

claude.ai/directory에서 등록 정보를 직접 확인할 수도 있습니다.
이렇게 하면 사용 중인 플랫폼용 StackQL MCP 서버가 인프로세스로 설치됩니다. 등록 정보는 macOS 유니버설, Windows x64, Linux x64 및 arm64용 서명된 바이너리를 포함하는 통합 멀티 플랫폼 번들을 제공하며, Claude Desktop이 머신에 맞는 바이너리를 자동으로 선택합니다. 네이티브 Windows ARM64의 경우 아래 다운로드에서 별도의 windows-arm64 번들을 설치하세요. Windows 바이너리는 Authenticode로 서명되었고 macOS 바이너리는 Apple에서 공증되었습니다. 이는 독립 실행형 StackQL 릴리스와 동일한 바이너리입니다.

Connector Directory에서 설치한 커넥터는 Claude Desktop의 환경을 상속하므로 Claude Desktop을 시작하기 전에 운영 체제 수준에서 프로바이더의 환경 변수를 설정하세요. 프로바이더별 자격 증명을 참조하세요. Claude Desktop은 시작할 때 환경을 캡처합니다. 변수를 변경한 후에는 Claude Desktop을 완전히 종료하고(Windows에서는 트레이 아이콘 포함) 다시 시작하세요. 에이전트에게 reload_credentials 도구를 실행하도록 요청하면 프로바이더별 자격 증명 상태가 보고되며, 이는 서버가 볼 수 있는 것과 볼 수 없는 것을 확인하는 가장 빠른 방법입니다.
Claude Desktop은 MCP 엘리시테이션(elicitation) 기능을 알리므로 기본 서버 모드(safe)에서는 변경 작업마다 승인을 요청합니다. 서버 모드를 참조하세요.
다운로드한 번들에서 설치
특정 버전을 고정하거나, Connector Directory에 액세스하지 않고 설치하거나, 설치 전에 체크섬을 직접 검증하려면 이 설치 옵션을 사용하세요.
미리 빌드된 MCP Bundle(.mcpb)은 서명된 stackql 바이너리와 서버 구성을 포함하는, 클릭 한 번으로 설치할 수 있는 패키지입니다. StackQL을 별도로 설치할 필요가 없습니다.
최신 릴리스에서 사용 중인 플랫폼용 번들을 다운로드하세요:
| 플랫폼 | 번들 |
|---|---|
| macOS (유니버설) | stackql-mcp-darwin-universal.mcpb |
| Windows AMD64 (x64) | stackql-mcp-windows-x64.mcpb |
| Windows ARM64 (네이티브) | stackql-mcp-windows-arm64.mcpb |
| Linux x64 | stackql-mcp-linux-x64.mcpb |
| Linux arm64 | stackql-mcp-linux-arm64.mcpb |
그런 다음 Claude Desktop에서 Settings -> Extensions -> Install Extension으로 이동하여 다운로드한 파일을 선택합니다. 번들에 포함된 바이너리는 Authenticode로 서명되었고(Windows) Apple에서 공증되었습니다(macOS). 릴리스 페이지에는 각 번들과 함께 .sha256 체크섬 파일이 있습니다. 설치 전에 검증하는 방법은 다음과 같습니다:
# macOS / Linux
shasum -a 256 -c stackql-mcp-darwin-universal.mcpb.sha256
이 서버는 공식 MCP 레지스트리에도 io.github.stackql/stackql-mcp 이름으로 등록되어 있으며, 이 레지스트리는 해당 체크섬을 고정합니다.
수동 구성
StackQL이 이미 설치되어 있으면 Claude Desktop의 구성 파일에 StackQL MCP 서버를 직접 등록할 수 있습니다.
사전 요구 사항
Claude Desktop에서 StackQL을 설정하기 전에 다음이 준비되어 있는지 확인하세요:
- StackQL 설치: stackql.io에서 StackQL을 다운로드하여 설치하거나 패키지 관리자를 사용하여 설치
- Claude Desktop: Anthropic 웹 사이트에서 다운로드
- 클라우드 제공업체 자격 증명: 사용하려는 클라우드 제공업체의 API 키 또는 자격 증명
다음 명령을 실행하여 StackQL이 시스템 PATH에 있는지 확인하세요:
stackql --version
MCP 서버 설정
Claude Desktop이 StackQL과 통신하도록 하려면 Claude Desktop 구성 파일에 MCP 서버를 구성하세요.
Windows
다음 위치에 있는 구성 파일을 편집하세요:
%APPDATA%\Claude\claude_desktop_config.json
macOS
다음 위치에 있는 구성 파일을 편집하세요:
~/Library/Application Support/Claude/claude_desktop_config.json
Linux
다음 위치에 있는 구성 파일을 편집하세요:
~/.config/Claude/claude_desktop_config.json
구성 예제
claude_desktop_config.json 파일에 다음 구성을 추가하세요:
{
"mcpServers": {
"stackql": {
"command": "stackql",
"args": [
"mcp",
"--mcp.server.type=stdio",
"--tls.allowInsecure"
],
"env": {
"GOOGLE_CREDENTIALS": "/path/to/google-credentials.json",
"AWS_ACCESS_KEY_ID": "your-aws-access-key-id",
"AWS_SECRET_ACCESS_KEY": "your-aws-secret-access-key",
"AZURE_CLIENT_ID": "your-azure-client-id",
"AZURE_CLIENT_SECRET": "your-azure-client-secret",
"AZURE_TENANT_ID": "your-azure-tenant-id",
"DATABRICKS_CLIENT_ID": "your-databricks-client-id",
"DATABRICKS_CLIENT_SECRET": "your-databricks-client-secret",
"OPENAI_API_KEY": "your-openai-api-key"
}
}
}
}
사용하려는 클라우드 제공업체의 환경 변수만 포함하면 됩니다. 사용하지 않는 프로바이더 자격 증명은 구성에서 제거하세요.
실제 자격 증명이 포함된 claude_desktop_config.json 파일을 버전 관리 시스템에 커밋하지 마세요. 안전한 자격 증명 관리 방식을 사용하세요.
Claude Desktop은 MCP 엘리시테이션 기능을 알리므로 기본 서버 모드(safe)에서는 변경 작업마다 승인을 요청합니다. 인벤토리 전용 액세스에는 mode: read_only 설정으로, 승인 요청을 건너뛰려면 mode: full_access 설정으로 전환하세요. 서버 모드를 참조하세요.
자격 증명 파일 사용(--env.file)
env 블록 대신 사용할 수 있는 방법(Windows에서는 권장 방법)은 자격 증명을 dotenv 스타일 파일에 보관하고 --env.file 플래그로 전달하는 것입니다:
{
"mcpServers": {
"stackql": {
"command": "stackql",
"args": [
"mcp",
"--mcp.server.type=stdio",
"--tls.allowInsecure",
"--env.file=C:\\Users\\me\\stackql-credentials.env"
]
}
}
}
최소 구성의 자격 증명 파일은 다음과 같습니다:
# stackql-credentials.env
GOOGLE_CREDENTIALS=/path/to/google-credentials.json
AWS_ACCESS_KEY_ID=your-aws-access-key-id
AWS_SECRET_ACCESS_KEY=your-aws-secret-access-key
이 방법이 env 블록보다 나은 이유:
env블록의 변경 사항은 Claude Desktop을 완전히 다시 시작해야(트레이 아이콘 종료 포함) MCP 하위 프로세스에 반영됩니다. 또한 Windows에서setx명령은 레지스트리에 기록하므로 실행 중인 Desktop 프로세스에는 전달되지 않습니다.--env.file플래그로 지정한 파일은 언제든지 생성하거나 교체할 수 있으며(서버가 시작될 때 존재하지 않아도 됩니다), 에이전트에게reload_credentials도구를 실행하도록 요청하면 다시 시작하지 않고도 변경 사항이 적용됩니다.
--env.file 플래그와 reload_credentials 도구는 StackQL v0.10.542 이후 릴리스에서 사용할 수 있습니다.
프로바이더별 자격 증명
클라우드 제공업체마다 필요한 인증 방법이 다릅니다. 원하는 프로바이더에 필요한 환경 변수는 프로바이더 문서(https://stackql.io/providers)를 참조하세요.
Claude Desktop 다시 시작
구성 파일을 업데이트한 후 Claude Desktop을 다시 시작하여 새 MCP 서버 구성을 로드하세요. 새 대화를 시작하면 StackQL MCP 서버가 자동으로 시작됩니다.
할 수 있는 작업
구성이 완료되면 Claude Desktop에서 자연어로 다음 작업을 수행할 수 있습니다:
클라우드 리소스 쿼리
Claude에게 클라우드 인프라에 대한 정보를 조회하도록 요청합니다:
- "us-central1 리전에 있는 내 GCP 컴퓨팅 인스턴스를 모두 보여 주세요"
- "내 AWS 계정의 S3 버킷을 모두 나열해 주세요"
- "내 구독에서 실행 중인 Azure 가상 머신은 무엇인가요?"
- "default 네임스페이스의 Kubernetes 파드를 모두 보여 주세요"
리소스 프로비저닝
대화형 명령으로 클라우드 리소스를 생성하고 배포합니다:
- "us-west-2에 'my-data-bucket'이라는 S3 버킷을 만들어 주세요"
- "버전 관리가 활성화된 GCP Cloud Storage 버킷을 배포해 주세요"
- "us-east-1에서 작은 EC2 인스턴스를 시작해 주세요"
- "westus2에 Azure 리소스 그룹을 만들어 주세요"
분석 및 감사
보안 감사 및 규정 준수 검사를 수행합니다:
- "공개적으로 액세스할 수 있는 S3 버킷을 모두 보여 주세요"
- "90일 동안 로그인하지 않은 IAM 사용자를 나열해 주세요"
- "적절한 라벨이 없는 GCP 인스턴스를 모두 찾아 주세요"
- "백업이 활성화되지 않은 Azure VM을 식별해 주세요"
클라우드 간 작업
여러 클라우드 제공업체의 리소스를 쿼리하고 비교합니다:
- "AWS, GCP, Azure의 모든 컴퓨팅 인스턴스를 보여 주세요"
- "AWS S3와 GCP Cloud Storage의 스토리지 비용을 비교해 주세요"
- "모든 클라우드 제공업체의 데이터베이스를 모두 나열해 주세요"
코드형 인프라
인프라 배포 쿼리를 생성하고 실행합니다:
- "VPC, 서브넷, EC2 인스턴스를 포함하는 리소스 스택을 만들어 주세요"
- "노드 풀이 포함된 완전한 GKE 클러스터를 배포해 주세요"
- "AWS에서 멀티 리전 배포를 설정해 주세요"
리소스 수정
기존 클라우드 리소스를 업데이트합니다:
- "태그가 없는 모든 EC2 인스턴스에 태그를 추가해 주세요"
- "S3 버킷 'my-bucket'의 암호화를 활성화해 주세요"
- "GCP 인스턴스 'web-server-1'의 머신 유형을 업데이트해 주세요"
- "내 Cloud Storage 버킷의 ACL을 비공개로 변경해 주세요"
리소스 삭제
더 이상 필요하지 않은 클라우드 리소스를 제거합니다:
- "S3 버킷 'temp-bucket'을 삭제해 주세요"
- "중지된 EC2 인스턴스를 모두 제거해 주세요"
- "사용하지 않는 GCP 디스크를 정리해 주세요"
대화 예제
다음은 StackQL을 사용하여 Claude Desktop과 상호 작용하는 방법의 예입니다:
사용자: "내 GCP 컴퓨팅 인스턴스를 모두 보여 주세요"
Claude: StackQL 쿼리를 실행하고 인스턴스 이름, 영역, 머신 유형, 상태를 보여 주는 서식이 지정된 표로 결과를 반환합니다
사용자: "us-central1 리전에 균일한 버킷 수준 액세스를 사용하는 'analytics-data-2025'라는 새 Cloud Storage 버킷을 만들어 주세요"
Claude: StackQL INSERT 문을 실행하여 버킷을 생성하고 생성되었음을 확인합니다
사용자: "이제 내 Cloud Storage 버킷을 모두 나열해 주세요"
Claude: SELECT 쿼리를 실행하고 새로 생성된 버킷을 포함한 모든 버킷을 보여 줍니다
팁 및 모범 사례
-
구체적인 요청: 요청이 구체적일수록 더 나은 결과를 얻을 수 있습니다. 가능하면 리소스 이름, 리전, 특정 속성을 포함하세요.
-
자연어 사용: SQL 구문을 알 필요가 없습니다. Claude가 자연어 요청을 StackQL 쿼리로 변환합니다.
-
실행 전 검토: 파괴적인 작업(DELETE, UPDATE)의 경우 Claude는 일반적으로 진행하기 전에 실행할 내용을 보여 줍니다.
-
다단계 작업: 하나의 대화에서 여러 작업을 연결할 수 있습니다. Claude는 세션 전체에서 컨텍스트를 유지합니다.
-
오류 처리: 쿼리가 실패하면 Claude가 문제 해결을 돕고 오류 메시지를 바탕으로 수정 사항을 제안할 수 있습니다.
-
기능 탐색: 구성된 프로바이더에 맞는 제안을 받으려면 Claude에게 "StackQL로 무엇을 할 수 있나요?"라고 물어보세요.
문제 해결
MCP 서버가 시작되지 않음
Claude Desktop이 StackQL MCP 서버에 연결할 수 없는 경우:
- StackQL이 PATH에 있는지 확인
claude_desktop_config.json파일이 유효한 JSON인지 확인- 구성의 파일 경로가 운영 체제에 맞는지 확인
- Claude Desktop 로그에서 오류 메시지 검토
인증 오류
인증 오류가 발생하는 경우:
- 클라우드 제공업체 자격 증명이 올바른지 확인
- 지정된 경로에 자격 증명 파일이 있는지 확인
- 구성에서 환경 변수의 형식이 올바른지 확인: 에이전트에게
reload_credentials도구를 실행하도록 요청하면 프로바이더별 자격 증명 상태가 보고되며, 이는 어떤 변수가 누락되었는지 확인하는 가장 빠른 방법입니다 - 자격 증명에 필요한 권한이 있는지 확인
권한 오류
권한이 부족하여 작업이 실패하는 경우:
- 서비스 계정 또는 IAM 사용자에게 필요한 권한이 있는지 확인
- 프로바이더별 IAM 정책 확인
- 클라우드 프로젝트에서 API 서비스가 활성화되어 있는지 확인
추가 정보
보안 고려 사항
- 자격 증명을 안전하게 저장하고 버전 관리 시스템에 커밋하지 마세요
- 서비스 계정에는 최소 권한 액세스 원칙을 적용하세요
- 자격 증명과 API 키를 정기적으로 교체하세요
- MCP 서버 로그에서 비정상적인 활동을 모니터링하세요
- 클라우드 제공업체의 자격 증명 관리 도구(예: Secret Manager, Parameter Store) 사용을 고려하세요