본문으로 건너뛰기
번역된 페이지

이 페이지는 AI의 도움을 받아 영어에서 번역되었습니다. 두 내용이 다를 경우 영어 버전을 기준으로 합니다.

설치

여기에서는 다양한 플랫폼에 StackQL을 설치하는 방법을 설명합니다.

macOS​

macOS에서는 Homebrew와 pkg 설치 관리자로 StackQL을 사용할 수 있습니다. 다중 아키텍처 설치 관리자 하나로 ARM(M1/Apple Silicon)과 AMD 아키텍처를 모두 지원합니다.

Homebrew로 설치하려면 터미널에서 다음 명령을 실행합니다:

brew install stackql

MCP 클라이언트에서 사용​

StackQL MCP 서버는 stdio를 통해 로컬에서 실행되므로, 어떤 클라이언트를 사용하든 프로바이더 자격 증명은 사용자의 머신에 그대로 남습니다. 아래에서 클라이언트를 선택하세요. 각 탭은 디렉터리 또는 원클릭 설치 방법을 먼저 안내하고, 대체 방법으로 수동 구성을 안내합니다. npx, Python, Docker, CI를 포함한 모든 배포 채널은 MCP 서버 설치를 참조하세요.

Claude Desktop​

Claude Desktop에 StackQL MCP 서버를 설치할 때 권장하는 방법은 Anthropic Connector Directory(Settings -> Connectors -> Add -> Browse Connectors에서 StackQL 검색)를 이용하는 것입니다. Claude Desktop이 플랫폼에 맞는 서명된 바이너리를 자동으로 선택합니다. 또는 다운로드한 파일로 설치할 수 있도록 모든 StackQL 릴리스에 사전 빌드된 MCP Bundle(.mcpb)이 첨부되어 있습니다. 어느 방법이든 StackQL을 별도로 설치할 필요는 없습니다. 번들은 macOS, Windows, Linux용으로 제공됩니다.

Linux 및 Windows MCPB 다운로드의 기본값은 amd64(x64)입니다. 드롭다운을 사용하여 amd64 또는 arm64를 선택하세요.


정보

StackQL MCP 서버는 Official MCP Registry에도 io.github.stackql/stackql-mcp 이름으로 등록되어 있습니다.

팁

번들은 StackQL MCP 서버를 실행하는 여러 방법 중 하나입니다. Claude Desktop의 전체 안내는 Claude Desktop에서 StackQL 사용을, npx, Docker, Python, CI 및 수동 옵션은 MCP 서버 설치를 참조하세요.

MCP 서버 설치​

StackQL MCP 서버를 사용하면 AI 에이전트가 StackQL로 클라우드 리소스를 쿼리하고 프로비저닝할 수 있습니다. 이 서버는 여러 채널로 배포됩니다. 모든 채널은 같은 서버를 실행하므로, 사용하는 클라이언트와 신뢰 요구 사항에 맞는 채널을 선택하세요. 아래 옵션은 신뢰도와 사용 편의성 순으로 대략 정렬되어 있습니다.

마켓플레이스 및 디렉터리​

이 서버는 Official MCP Registry에 io.github.stackql/stackql-mcp 이름으로 게시되어 있습니다. 아래의 패키지 레지스트리는 배포 가능한 아티팩트를 제공하며, 다운스트림 디렉터리는 그곳에서 등록 정보를 가져옵니다.

레지스트리유형게시 방법등록 페이지참고
Official MCP Registry정식 메타데이터 레지스트리mcp-publisher CLI + server.jsonmodelcontextprotocol.io/search
modelcontextprotocol.io/direct
8개 패키지(mcpb x5, oci, npm, pypi)를 모두 알림
npm패키지 레지스트리npm publish@stackql/mcp-servernpx 런처
PyPI패키지 레지스트리twine uploadstackql-mcp-serveruvx / pip 런처
Docker Hub컨테이너 레지스트리docker buildx --pushstackql/stackql-mcp다중 아키텍처 amd64 + arm64
GitHub Actions MarketplaceCI 마켓플레이스(setup-stackql-mcp 액션)공개 리포지토리 + 릴리스 + 마켓플레이스 등록setup-stackql-mcp-server인증된 게시자, stackql/setup-stackql-mcp

사전 빌드된 .mcpb 번들​

사용 시기: Connector Directory에 액세스할 수 없는 Claude Desktop 환경이거나, 특정 버전을 고정하거나 설치 전에 체크섬을 직접 검증하려는 경우입니다. 대부분의 Claude Desktop 사용자에게는 Anthropic Connector Directory가 권장 설치 방법입니다.

모든 StackQL 릴리스에는 플랫폼별로 사전 빌드된 MCP Bundle이 첨부되어 있습니다:

https://releases.stackql.io/stackql/latest/stackql-mcp-<platform>.mcpb

여기서 <platform> 값은 darwin-universal, windows-x64(AMD64), windows-arm64, linux-x64, linux-arm64 중 하나입니다. 플랫폼별 다운로드 버튼은 MCP 클라이언트에서 사용 섹션의 Claude Desktop 탭에 있습니다. 각 번들에 해당하는 .sha256 체크섬은 릴리스 페이지에 있습니다. 체크섬을 검증한 다음 Claude Desktop의 Settings -> Extensions에서 설치하세요:

shasum -a 256 -c stackql-mcp-darwin-universal.mcpb.sha256

전체 안내는 Claude Desktop에서 StackQL 사용을 참조하세요.

claude_desktop_config.json 수동 구성​

사용 시기: stackql 바이너리가 이미 PATH에 있고 Claude Desktop 또는 다른 stdio MCP 클라이언트를 사용하는 경우입니다.

{
"mcpServers": {
"stackql": {
"command": "stackql",
"args": [
"mcp",
"--mcp.server.type=stdio",
"--approot", "/Users/you/.stackql",
"--mcp.config", "{\"server\": {\"audit\": {\"disabled\": true}}}"
]
}
}
}

세 인수 모두 반드시 필요합니다:

  • --mcp.server.type=stdio 인수는 편집기에 내장된 클라이언트가 사용하는 stdio 전송 방식을 선택합니다.
  • --approot 인수는 프로바이더 캐시가 쓰기 가능한 디렉터리를 가리키도록 합니다. MCP 클라이언트는 작업 디렉터리를 쓰기 불가능한 / 디렉터리로 설정한 상태로 서버를 시작할 수 있습니다.
  • --mcp.config '{"server": {"audit": {"disabled": true}}}' 인수는 감사 로그를 비활성화합니다. 이 인수가 없으면 감사 로그 디렉터리의 기본값은 (쓰기 불가능할 수 있는) 작업 디렉터리가 됩니다.

"env" 블록으로 프로바이더 자격 증명을 추가하고 "mode" 키로 안전 계약을 조정하세요. 자세한 내용은 서버 모드를 참조하세요.

npx(설치 불필요)​

사용 시기: StackQL을 전역으로 설치하지 않으려는 경우, 모든 Node 환경에서 사용할 수 있습니다.

{ "mcpServers": { "stackql": { "command": "npx", "args": ["-y", "@stackql/mcp-server"] } } }

@stackql/mcp-server 런처는 처음 실행할 때 서명된 stackql 바이너리를 다운로드하고 SHA-256을 검증한 다음, 이후 실행을 위해 캐시합니다.

uvx / pip (Python)​

사용 시기: Python 환경입니다. Python용으로 패키징된 같은 런처이며, npx 런처가 채우는 바이너리 캐시를 공유합니다.

{ "mcpServers": { "stackql": { "command": "uvx", "args": ["stackql-mcp-server"] } } }

또는 pip install stackql-mcp-server 명령(Python 3.9+)으로 현재 환경에 설치할 수 있습니다. 패키지는 PyPI의 stackql-mcp-server입니다.

Docker​

사용 시기: 컨테이너화되었거나 그 밖의 방식으로 격리된 런타임입니다. 이미지는 다중 아키텍처(amd64 및 arm64)를 지원합니다.

docker run -i --rm stackql/stackql-mcp

클라이언트 구성으로는 다음과 같습니다:

{ "mcpServers": { "stackql": { "command": "docker", "args": ["run", "-i", "--rm", "stackql/stackql-mcp"] } } }

이미지는 Docker Hub의 stackql/stackql-mcp입니다.

CI 및 에이전트형 워크플로(GitHub Actions)​

사용 시기: CI의 일부로 에이전트가 클라우드를 쿼리하고, 허용하는 경우 클라우드에서 작업도 수행할 수 있도록 GitHub Actions 작업 안에서 서버를 실행합니다.

stackql/setup-stackql-mcp@v1 액션은 바이너리를 설치하고 MCP 구성을 작성합니다(기본값은 read_only 모드). 이 구성을 claude_args 입력을 통해 anthropics/claude-code-action 액션에 전달합니다:

- id: stackql
uses: stackql/setup-stackql-mcp@v1
with:
auth: '{"github":{"type":"null_auth"}}'

- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: |
Using stackql, list the public repositories in the stackql org and
summarise them as a markdown table.
claude_args: |
--mcp-config ${{ steps.stackql.outputs.mcp-config-file }}
--allowedTools 'mcp__stackql__*'

더 많은 에이전트형 레시피(클라우드 감사, 비용 추정 등)는 액션 README를 참조하세요.

임베디드 MCP​

사용 시기: 에이전트형 앱을 빌드하면서 MCP 서버를 자체 바이너리에 벤더링하려는 경우입니다. npx, 별도 설치, 런타임 종속성이 모두 필요 없습니다.

네이티브 라이브러리는 각 언어의 공식 MCP SDK 클라이언트 뒤에서 서명된 stackql 바이너리를 stdio로 실행합니다. 따라서 앱은 레지스트리의 모든 프로바이더에 대해 거버넌스가 적용된 동일한 SQL 인터페이스를 사용할 수 있습니다. 각 라이브러리의 기본값은 read_only 모드이며, 쓰기 가능한 모드로의 승격은 항상 명시적으로 이루어집니다. 또한 처음 실행할 때 바이너리를 다운로드하고 검증하거나, 바이너리를 빌드에 벤더링하여 자체 포함된 단일 실행 파일을 만들 수 있습니다. 언어별 전체 API는 임베디드 MCP 참조에 있습니다.

stackql-mcp 크레이트는 rmcp 클라이언트 뒤에서 바이너리를 실행합니다. 기본 sidecar 기능은 처음 실행할 때 바이너리를 다운로드하고 검증합니다. vendored 기능은 include_bytes! 매크로로 바이너리를 내장하여 자체 포함된 단일 바이너리를 만듭니다. MSRV는 Rust 1.88입니다.

# Cargo.toml
stackql-mcp = "0.1"
use stackql_mcp::{Mode, StackqlMcp};

let server = StackqlMcp::builder()
.mode(Mode::ReadOnly)
.start()
.await?;
let tools = server.list_all_tools().await?;

전체 참조: 임베디드 MCP: Rust.

신뢰 모델​

모든 채널에 동일한 보안 속성이 적용됩니다:

  • 내장된 stackql 바이너리는 Authenticode로 서명(Windows)되고 Apple의 공증(macOS)을 받았습니다.
  • 모든 .mcpb 번들에는 릴리스 페이지에 게시된 SHA-256 체크섬이 함께 제공됩니다.
  • npx 및 uvx 런처는 처음 사용하기 전에 다운로드한 바이너리의 SHA-256을 검증합니다.
  • MCP Registry 항목은 플랫폼별 해시를 증명합니다.

GitHub Actions 사용​

GitHub Actions 워크플로에서 StackQL GitHub Actions를 사용할 수 있습니다. 다음 액션을 사용할 수 있습니다:

stackql-deploy​

GitHub 워크플로에서 직접 StackQL을 사용하여 인프라 스택을 배포하거나 테스트합니다. 이 액션은 SQL과 유사한 구문을 사용하는 코드형 인프라(IaC) 워크플로를 지원하므로, 단일 워크플로에서 여러 프로바이더에 걸쳐 클라우드 리소스를 정의, 배포, 관리할 수 있습니다.


사용 예

...
jobs:
stackql-actions-test:
name: StackQL Actions Test
runs-on: ubuntu-latest
env:
GOOGLE_CREDENTIALS: ${{ secrets.GOOGLE_CREDENTIALS }} # add additional cloud provider creds here as needed

steps:
- name: Checkout
uses: actions/checkout@v6

- name: Deploy a Stack
uses: stackql/stackql-deploy-action@v2
with:
command: 'build'
stack_dir: 'examples/k8s-the-hard-way'
stack_env: 'dev'
env_vars: |
GOOGLE_PROJECT=stackql-k8s-the-hard-way-demo
GOOGLE_REGION=australia-southeast1

기타 라이브러리​

StackQL은 다양한 프로그래밍 언어와 환경에서 사용할 수 있는 여러 통합 방법을 제공합니다. 이러한 라이브러리는 StackQL의 기능을 확장하여 클라우드 리소스 쿼리 및 관리를 기존 애플리케이션과 워크플로에 쉽게 통합할 수 있게 합니다.

pystackql Python 패키지​

Python 프로그램에서 StackQL을 사용하기 위한 Python 래퍼입니다. pystackql 패키지는 PyPI에서 제공되며, pystackql 패키지에 대한 문서는 Read the Docs에서 볼 수 있습니다. pystackql 패키지를 설치하려면 다음 명령을 실행합니다:

pip install pystackql

다음 예제는 pystackql 패키지를 pandas 라이브러리와 함께 사용하여 StackQL 쿼리를 실행하고 결과를 pandas.DataFrame 객체로 반환하는 방법을 보여 줍니다:

from pystackql import StackQL
import pandas as pd
region = "ap-southeast-2"
stackql = StackQL()

query = """
SELECT instance_type, COUNT(*) as num_instances
FROM aws.ec2.instances
WHERE region = '%s'
GROUP BY instance_type
""" % (region)

res = stackql.execute(query)
df = pd.read_json(res)
print(df)