이 페이지는 AI의 도움을 받아 영어에서 번역되었습니다. 두 내용이 다를 경우 영어 버전을 기준으로 합니다.
설치
여기에서는 다양한 플랫폼에 StackQL을 설치하는 방법을 설명합니다.
- macOS
- Linux
- Windows
- Docker
- stackql-deploy
- 클라우드 셸
macOS
macOS에서는 Homebrew와 pkg 설치 관리자로 StackQL을 사용할 수 있습니다. 다중 아키텍처 설치 관리자 하나로 ARM(M1/Apple Silicon)과 AMD 아키텍처를 모두 지원합니다.
- Homebrew
- curl(서명 및 공증된 바이너리)
- 패키지 다운로드
Homebrew로 설치하려면 터미널에서 다음 명령을 실행합니다:
brew install stackql
서명 및 공증된 stackql 실행 바이너리를 현재 디렉터리에 설치하려면 터미널에서 다음 명령을 실행합니다:
curl -fsSL https://get-stackql.io/install | sh
StackQL은 macOS용으로 서명 및 공증된 대화형 pkg 설치 관리자로 제공됩니다.
Linux
StackQL은 모든 Linux 아키텍처에서 사용할 수 있습니다.
- curl
- 패키지 다운로드
사용 중인 Linux 아키텍처(amd64 또는 arm64)용 stackql 실행 바이너리를 현재 디렉터리에 설치하려면 터미널에서 다음 명령을 실행합니다:
curl -fsSL https://get-stackql.io/install | sh
또는 여기에서 바이너리를 다운로드할 수 있습니다:
Windows
Windows에서는 Chocolatey, PowerShell 설치 스크립트, MSI 설치 관리자로 StackQL을 사용할 수 있습니다. 네이티브 AMD64(x64) 및 ARM64 빌드는 MSI 설치 관리자와 stackql.exe 파일이 포함된 ZIP 아카이브로 제공됩니다. AMD64 빌드는 에뮬레이션을 통해 ARM64에서도 실행됩니다. 모든 실행 파일은 Authenticode 코드 서명 인증서로 서명되어 있습니다.
- Chocolatey
- Invoke-RestMethod
- MSI/ZIP 다운로드
Chocolatey로 설치하려면 PowerShell 또는 cmd 터미널에서 다음 명령을 실행합니다:
choco install stackql
Authenticode 서명 실행 파일을 현재 디렉터리에 설치하려면 PowerShell 터미널에서 다음을 실행합니다:
Invoke-RestMethod https://get-stackql.io/install | Invoke-Expression
# or
irm https://get-stackql.io/install | iex
아래에서 서명된 Windows용 stackql 설치 관리자 또는 실행 파일을 다운로드하세요. 다운로드 버튼을 클릭하면 기본적으로 AMD64가 선택됩니다. AMD64 또는 네이티브 ARM64를 선택하려면 버튼의 드롭다운을 사용하세요.
stackql-deploy
stackql-deploy 도구는 StackQL을 기반으로 구축된 상태 비저장 IaC 프레임워크입니다. 전체 문서는 StackQL Deploy 문서를 참조하세요.
Linux / macOS
최신 stackql-deploy 바이너리를 한 번에 다운로드하고 압축을 풉니다. 설치 관리자는 OS와 아키텍처(유니버설 macOS 바이너리를 통한 Apple Silicon 및 Intel 포함)를 감지하고 올바른 릴리스 자산을 자동으로 가져옵니다.
curl -fsSL https://get-stackql-deploy.io/install.sh | sh
Windows
최신 stackql-deploy 바이너리를 현재 디렉터리에 다운로드하고 압축을 풉니다.
설치 관리자는 플랫폼을 감지하고 올바른 릴리스 자산을 자동으로 가져옵니다.
irm https://get-stackql-deploy.io/install.ps1 | iex
cargo
Rust 도구 체인이 설치되어 있으면 이 명령은 crates.io에서 바이너리를 직접 빌드하고 설치합니다.
cargo install stackql-deploy
클라우드 셸
StackQL은 주요 클라우드 및 데이터 플랫폼에 내장된 클라우드 셸과 웹 터미널에서 직접 사용할 수 있습니다. 이러한 환경에는 로그인한 ID의 권한이 미리 부여되어 있습니다. 따라서 별도의 인증 설정이 필요 없어 원활하게 사용할 수 있습니다.
- AWS
- Azure
- Databricks
AWS CloudShell
AWS CloudShell은 AWS CLI가 사전 설치 및 인증된 브라우저 기반 셸을 제공합니다. AWS CloudShell에서 StackQL을 실행하면 추가 인증 단계 없이 AWS 리소스를 쿼리하고 관리할 수 있습니다. 자세한 지침은 AWS CloudShell 튜토리얼을 참조하세요.
먼저 StackQL 패키지를 다운로드합니다:
curl -fsSL https://get-stackql.io/install/aws | sh
그런 다음 StackQL AWS CloudShell 스크립트를 실행합니다:
./stackql-aws-cloud-shell.sh
이 스크립트는 AWS CloudShell 자격 증명을 사용하는 StackQL 명령 셸을 시작하므로 바로 AWS 리소스 쿼리를 시작할 수 있습니다.
Azure Cloud Shell
Azure Cloud Shell은 Azure CLI가 Azure 계정으로 사전 인증된 셸 환경을 브라우저에서 제공합니다. Azure Cloud Shell에서 StackQL을 사용하면 추가 설정 없이 Azure 리소스를 원활하게 쿼리할 수 있습니다. 자세한 내용은 Azure Cloud Shell 가이드를 참조하세요.
먼저 StackQL 패키지를 다운로드합니다:
curl -fsSL https://get-stackql.io/install/azure | sh
그런 다음 StackQL Azure Cloud Shell 스크립트를 실행합니다:
./stackql-azure-cloud-shell.sh
이 스크립트는 Azure Cloud Shell 자격 증명을 사용하도록 StackQL 세션을 자동으로 구성하므로 바로 Azure 리소스를 쿼리할 수 있습니다.
Google Cloud Shell
Google Cloud Shell은 Google Cloud CLI가 이미 인증된 개발 및 운영 환경을 제공합니다. Google Cloud Shell에서 StackQL을 실행하면 기존 인증을 사용하여 GCP 리소스를 쿼리할 수 있습니다. 자세한 내용은 Google Cloud Shell 가이드를 참조하세요.
먼저 StackQL 패키지를 다운로드합니다:
curl -fsSL https://get-stackql.io/install/google | sh
그런 다음 StackQL Google Cloud Shell 스크립트를 실행합니다:
./stackql-google-cloud-shell.sh
이 스크립트는 Google Cloud Shell 자격 증명을 사용하도록 StackQL을 설정하므로 SQL 구문으로 바로 GCP 리소스 쿼리를 시작할 수 있습니다.
Databricks 웹 터미널
Databricks 작업 영역에는 로그인한 사용자로 실행되는 웹 터미널이 포함되어 있습니다. 이 터미널에서 StackQL을 실행하면 별도의 인증 설정 없이 Databricks ID로 작업 영역을 쿼리할 수 있습니다. 예제 쿼리와 계정 수준 인증은 Databricks 웹 터미널 가이드를 참조하세요.
먼저 StackQL 패키지를 다운로드합니다:
curl -fsSL https://get-stackql.io/install/databricks | sh
그런 다음 StackQL Databricks 셸 스크립트를 실행합니다:
./stackql-databricks-shell.sh
이 스크립트는 Databricks 작업 영역 ID를 사용하는 StackQL 세션을 시작하므로 databricks_workspace.iam.vw_user_entitlements 같은 작업 영역 범위의 리소스를 바로 쿼리할 수 있습니다. 계정 수준 쿼리(프로비저닝, 청구, 계정 IAM)를 실행하려면 가이드의 설명에 따라 Databricks OAuth2 서비스 주체 변수를 설정하세요.
MCP 클라이언트에서 사용
StackQL MCP 서버는 stdio를 통해 로컬에서 실행되므로, 어떤 클라이언트를 사용하든 프로바이더 자격 증명은 사용자의 머신에 그대로 남습니다. 아래에서 클라이언트를 선택하세요. 각 탭은 디렉터리 또는 원클릭 설치 방법을 먼저 안내하고, 대체 방법으로 수동 구성을 안내합니다. npx, Python, Docker, CI를 포함한 모든 배포 채널은 MCP 서버 설치를 참조하세요.
- Claude Desktop
- ChatGPT
- Goose
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 서버 설치를 참조하세요.
ChatGPT 및 Codex
StackQL은 ChatGPT 데스크톱 앱과 Codex CLI용 로컬 플러그인으로 제공됩니다. 플러그인은 사용자의 머신에서 stdio를 통해 StackQL MCP 서버를 실행하므로 프로바이더 자격 증명이 머신 밖으로 나가지 않습니다. Node.js 24.22.1 이상이 필요합니다(해당 릴리스 라인에서는 22.23.4 또는 26.12.1). 플러그인은 Node.js 기본 제공 모듈만 사용하며, 처음 사용할 때 서명된 stackql 바이너리를 다운로드하고 SHA-256을 검증합니다.
ChatGPT 데스크톱 앱(플러그인 디렉터리):
ChatGPT 데스크톱 앱에서 플러그인 디렉터리를 열고 StackQL을 검색한 다음 Install을 클릭하고 플러그인 설정을 실행하세요. 함께 제공되는 stackql-setup 스킬이 자격 증명 설정과 첫 번째 쿼리를 안내합니다. 등록 항목에는 Desktop only 배지가 붙어 있습니다. 플러그인은 ChatGPT 웹이나 모바일이 아닌 데스크톱 앱에서만 설치되며, 플러그인의 도구는 Work 모드, 즉 사용자의 컴퓨터에서 실행되는 스레드에서 사용할 수 있습니다. 디렉터리에 아직 등록 항목이 표시되지 않으면 대신 리포지토리 마켓플레이스에서 설치하세요.
ChatGPT 데스크톱 앱(리포지토리 마켓플레이스):
Settings -> Plugins -> Add -> Add from GitHub 메뉴를 열고 stackql/stackql 리포지토리를 입력한 다음, 플러그인 디렉터리의 Personal 섹션에서 StackQL을 설치하고 앱을 다시 시작하세요.
Codex CLI:
codex plugin marketplace add stackql/stackql --sparse .agents/plugins --sparse packaging/openai-plugin
codex plugin add stackql@stackql
ChatGPT 데스크톱 또는 Codex를 다시 시작한 후 다음과 같이 요청해 보세요: StackQL을 사용해서 필요하면 GitHub 프로바이더를 설치하고, 처음 5개의 GitHub 서비스를 나열해 주세요. 프로바이더 자격 증명은 각 프로바이더의 표준 환경 변수 이름(예: AWS_ACCESS_KEY_ID 및 AWS_SECRET_ACCESS_KEY)으로 ~/.stackql/.env 파일에 넣습니다. 파일을 편집한 후에는 에이전트에게 reload_credentials 도구를 호출하도록 요청하세요.
플러그인 없이 사용:
Settings -> Plugins -> MCPs -> Connect to a custom MCP에서 STDIO를 선택하고, 명령을 npx로 설정한 다음 인수 -y 및 @stackql/mcp-server를 추가하세요. 프로바이더 자격 증명은 같은 양식에서 환경 변수로 제공하세요.
ChatGPT 웹과 모바일은 로컬 stdio 서버를 실행할 수 없으므로 플러그인은 데스크톱과 Codex에서만 사용할 수 있습니다. 아직 해결되지 않은 ChatGPT 데스크톱 버그(openai/codex#38162)로 인해 Chat 세션에서 로컬 MCP 도구가 표시되지 않을 수 있습니다. Work 모드 스레드, Codex 스레드, Codex CLI는 영향을 받지 않습니다.
Goose
Goose는 stdio 확장을 직접 실행하므로 npx 런처만 있으면 됩니다(Node.js 18 이상).
Goose Desktop: 아래 버튼을 클릭하세요. Goose가 열리고, 실행할 명령을 표시하여 확인을 요청한 다음 StackQL을 확장으로 추가합니다.
이 버튼은 goose:// 딥 링크입니다. 링크를 브라우저 주소 표시줄에 붙여 넣거나, 터미널에서 open(macOS), start(Windows) 또는 xdg-open(Linux) 명령으로 열 수도 있습니다:
goose://extension?cmd=npx&arg=-y&arg=%40stackql%2Fmcp-server&id=stackql&name=StackQL&description=Query%20and%20provision%20cloud%20and%20SaaS%20resources%20with%20SQL
Goose CLI:
goose session --with-extension "npx -y @stackql/mcp-server"
또는 goose configure 명령을 실행하고 Add Extension -> Command-line Extension을 선택한 다음 같은 명령을 입력하세요. 입력하라는 메시지가 표시되면 프로바이더 자격 증명을 확장의 환경 변수로 제공하세요.
Goose는 앱 내 확장 디렉터리를 폐지하고 Official MCP Registry로 전환했습니다. StackQL은 이 레지스트리에 io.github.stackql/stackql-mcp 이름으로 등록되어 있습니다. Goose가 레지스트리 가져오기 기능을 제공하면 별도의 조치 없이 Goose에서 StackQL을 찾을 수 있습니다.
MCP 서버 설치
StackQL MCP 서버를 사용하면 AI 에이전트가 StackQL로 클라우드 리소스를 쿼리하고 프로비저닝할 수 있습니다. 이 서버는 여러 채널로 배포됩니다. 모든 채널은 같은 서버를 실행하므로, 사용하는 클라이언트와 신뢰 요구 사항에 맞는 채널을 선택하세요. 아래 옵션은 신뢰도와 사용 편의성 순으로 대략 정렬되어 있습니다.
마켓플레이스 및 디렉터리
이 서버는 Official MCP Registry에 io.github.stackql/stackql-mcp 이름으로 게시되어 있습니다. 아래의 패키지 레지스트리는 배포 가능한 아티팩트를 제공하며, 다운스트림 디렉터리는 그곳에서 등록 정보를 가져옵니다.
- 레지스트리
- 디렉터리
| 레지스트리 | 유형 | 게시 방법 | 등록 페이지 | 참고 |
|---|---|---|---|---|
| Official MCP Registry | 정식 메타데이터 레지스트리 | mcp-publisher CLI + server.json | modelcontextprotocol.io/searchmodelcontextprotocol.io/direct | 8개 패키지(mcpb x5, oci, npm, pypi)를 모두 알림 |
| npm | 패키지 레지스트리 | npm publish | @stackql/mcp-server | npx 런처 |
| PyPI | 패키지 레지스트리 | twine upload | stackql-mcp-server | uvx / pip 런처 |
| Docker Hub | 컨테이너 레지스트리 | docker buildx --push | stackql/stackql-mcp | 다중 아키텍처 amd64 + arm64 |
| GitHub Actions Marketplace | CI 마켓플레이스(setup-stackql-mcp 액션) | 공개 리포지토리 + 릴리스 + 마켓플레이스 등록 | setup-stackql-mcp-server | 인증된 게시자, stackql/setup-stackql-mcp |
디렉터리 및 애그리게이터 등록 목록입니다. 검색 노출 측면의 중요도 순으로 대략 정렬되어 있습니다:
| 디렉터리 | 유형 | 등록 페이지 |
|---|---|---|
| Anthropic Connector Directory | Claude Desktop 앱 내 디렉터리 | claude.ai/directory |
| OpenAI Plugin Directory | ChatGPT 데스크톱 앱 내 디렉터리(데스크톱 전용) | ChatGPT 데스크톱 앱에서 StackQL 검색, ChatGPT 및 Codex 참조 |
| Cursor Directory | IDE 클라이언트 디렉터리 | cursor.directory |
| mcp.so | 최대 규모의 애그리게이터 | mcp.so |
| PulseMCP | 검색 노출, 레지스트리 후원사 | pulsemcp |
| Glama.ai MCP | 검색 가능한 마켓플레이스 | glama.ai |
| mcpmarket.com | 애그리게이터 | mcpmarket |
| mcpservers.org | Awesome 목록 사이트 | mcpservers.org |
사전 빌드된 .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 참조에 있습니다.
- Rust
- Go
- Kotlin / JVM
- .NET
- Gleam
- Swift
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-mcp-go 라이브러리는 공식 Go MCP SDK 클라이언트 뒤에서 바이너리를 실행합니다. go:embed 지시문으로 바이너리를 벤더링하여 자체 포함된 단일 바이너리를 만들거나, 처음 실행할 때 바이너리를 다운로드하고 검증하도록 할 수 있습니다. 기본적으로 read_only 모드로 시작합니다.
go get github.com/stackql/stackql-mcp-go
import (
"context"
stackqlmcp "github.com/stackql/stackql-mcp-go/embed"
)
client, err := stackqlmcp.StartServer(ctx, stackqlmcp.Options{
Binary: StackqlMCPBinary(),
})
defer client.Close()
전체 참조: 임베디드 MCP: Go.
io.stackql:stackql-mcp 라이브러리는 공식 Kotlin MCP SDK 클라이언트 뒤에서 바이너리를 실행하며, 함께 제공되는 Gradle 플러그인은 같은 실행 과정을 빌드에 연결합니다. JDK 17 및 Kotlin 2.x가 필요합니다.
dependencies {
implementation("io.stackql:stackql-mcp:0.1.0")
}
import io.stackql.mcp.Mode
import io.stackql.mcp.StackqlMcp
val server = StackqlMcp.builder().mode(Mode.ReadOnly).start()
server.use {
val tools = server.client.listTools().tools
}
전체 참조: 임베디드 MCP: Kotlin / JVM.
StackQL.Mcp 패키지는 공식 C# MCP SDK 클라이언트 뒤에서 바이너리를 실행합니다. 기본적으로 사이드카 방식이며, 번들을 빌드 리소스로 벤더링하여 자체 포함된 실행 파일을 만들 수도 있습니다. .NET 8 이상이 필요합니다.
dotnet add package StackQL.Mcp
using StackQL.Mcp;
await using var server = await StackqlMcp.CreateBuilder()
.WithMode(StackqlMode.ReadOnly)
.StartAsync();
var tools = await server.ListToolsAsync();
전체 참조: 임베디드 MCP: .NET / C#.
stackql_mcp 라이브러리는 Erlang/BEAM 런타임을 대상으로 하며 child_spec() 함수를 통해 서버를 OTP 자식 프로세스로 노출하므로 자체 슈퍼비전 트리 안에 배치할 수 있습니다. 기본적으로 read_only 모드로 시작합니다.
gleam add stackql_mcp
import envoy
import stackql_mcp
let assert Ok(server) =
stackql_mcp.start(
config: stackql_mcp.default_config(),
home: "/home/u", os: "linux", arch: "x86_64",
getenv: envoy.get,
)
let assert Ok(tools) = stackql_mcp.list_tools(server)
전체 참조: 임베디드 MCP: Gleam.
stackql-mcp-swift 패키지는 공식 Swift MCP SDK 클라이언트 뒤에서 바이너리를 실행합니다. darwin-universal 바이너리는 Developer ID로 서명되고 Apple의 공증을 받았으므로, 서명된 .app 번들 안에 포함해도 앱의 공증이 유효하게 유지됩니다. macOS 13+ 및 Swift 6.1(Xcode 16.3+)이 필요합니다.
// Package.swift
.package(url: "https://github.com/stackql/stackql-mcp-swift.git", from: "0.1.0")
import StackQLMCP
var options = Options()
options.mode = .readOnly
let server = try await StackQLServer.start(options)
let tools = try await server.listToolNames()
await server.stop()
전체 참조: 임베디드 MCP: Swift.
신뢰 모델
모든 채널에 동일한 보안 속성이 적용됩니다:
- 내장된
stackql바이너리는 Authenticode로 서명(Windows)되고 Apple의 공증(macOS)을 받았습니다. - 모든
.mcpb번들에는 릴리스 페이지에 게시된 SHA-256 체크섬이 함께 제공됩니다. npx및uvx런처는 처음 사용하기 전에 다운로드한 바이너리의 SHA-256을 검증합니다.- MCP Registry 항목은 플랫폼별 해시를 증명합니다.
GitHub Actions 사용
GitHub Actions 워크플로에서 StackQL GitHub Actions를 사용할 수 있습니다. 다음 액션을 사용할 수 있습니다:
- stackql-deploy
- setup-stackql
- setup-stackql-mcp
- stackql-exec
- stackql-assert
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
setup-stackql
GitHub Actions 워크플로에서 StackQL을 설정합니다.
사용 예
- name: setup StackQL
uses: stackql/setup-stackql@v2
with:
use_wrapper: true
- name: Use GitHub Provider
run: |
stackql exec -i ./examples/github-example.iql
env:
STACKQL_GITHUB_USERNAME: ${{ secrets.STACKQL_GITHUB_USERNAME }}
STACKQL_GITHUB_PASSWORD: ${{ secrets.STACKQL_GITHUB_PASSWORD }}
setup-stackql-mcp
GitHub Actions 워크플로에 StackQL MCP 서버를 설치합니다. 이 액션은 서명된 바이너리를 설치하고 mcpServers 구성(기본값은 read_only 모드)을 작성합니다. anthropics/claude-code-action 같은 에이전트형 단계는 claude_args 입력을 통해 이 구성을 사용합니다.
사용 예
- 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__*'
stackql-exec
GitHub Actions 워크플로에서 StackQL 명령을 실행합니다. 쿼리는 인라인으로 지정하거나 리포지토리의 파일에서 제공할 수 있습니다.
사용 예
- name: exec github example
uses: stackql/stackql-exec@v2
with:
query: |
select total_private_repos
from github.orgs.orgs
where org = 'stackql'
env:
STACKQL_GITHUB_USERNAME: ${{ secrets.STACKQL_GITHUB_USERNAME }}
STACKQL_GITHUB_PASSWORD: ${{ secrets.STACKQL_GITHUB_PASSWORD }}
stackql-assert
GitHub Actions 워크플로에서 단위 테스트를 수행합니다(보증, 거버넌스 또는 클라우드 보안 점검용).
사용 예
- name: Use test query string and expected rows
uses: stackql/stackql-assert@v2
with:
test_query: |
SELECT name
FROM google.compute.instances
WHERE project = 'stackql-demo' AND zone = 'australia-southeast1-a' AND name = 'stackql-demo-001';
expected_rows: 1
env:
GOOGLE_CREDENTIALS: ${{ secrets.GOOGLE_CREDENTIALS }}
기타 라이브러리
StackQL은 다양한 프로그래밍 언어와 환경에서 사용할 수 있는 여러 통합 방법을 제공합니다. 이러한 라이브러리는 StackQL의 기능을 확장하여 클라우드 리소스 쿼리 및 관리를 기존 애플리케이션과 워크플로에 쉽게 통합할 수 있게 합니다.
- pystackql
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)