Lewati ke konten utama
Halaman terjemahan

Halaman ini diterjemahkan dari bahasa Inggris dengan bantuan AI. Jika keduanya berbeda, versi bahasa Inggris menjadi acuannya.

Instalasi

Halaman ini berisi petunjuk untuk menginstal StackQL di berbagai platform.

macOS​

StackQL tersedia di macOS melalui Homebrew dan penginstal pkg; arsitektur ARM (M1/Apple Silicon) dan AMD sama-sama didukung oleh satu penginstal multiarsitektur.

Untuk menginstal melalui Homebrew, jalankan perintah berikut di terminal Anda:

brew install stackql

Menggunakan dengan klien MCP​

Server MCP StackQL berjalan secara lokal melalui stdio, sehingga kredensial provider tetap berada di mesin Anda, apa pun klien yang Anda gunakan. Pilih klien Anda di bawah ini: setiap tab menampilkan cara melalui direktori atau satu klik terlebih dahulu, dan konfigurasi manual sebagai fallback. Untuk semua saluran distribusi, termasuk npx, Python, Docker, dan CI, lihat Menginstal server MCP.

Claude Desktop​

Cara yang direkomendasikan untuk menginstal server MCP StackQL ke Claude Desktop adalah melalui Anthropic Connector Directory (Settings -> Connectors -> Add -> Browse Connectors, cari StackQL) - Claude Desktop memilih biner yang ditandatangani dan sesuai untuk platform Anda secara otomatis. Sebagai alternatif, MCP Bundle (.mcpb) siap pakai dilampirkan pada setiap rilis StackQL untuk instalasi dari file yang diunduh - dengan cara mana pun, Anda tidak perlu menginstal StackQL secara terpisah. Bundle tersedia untuk macOS, Windows, dan Linux.

Unduhan MCPB untuk Linux dan Windows secara default menggunakan amd64 (x64). Gunakan menu dropdown untuk memilih amd64 atau arm64.


info

Server MCP StackQL juga tercantum di Official MCP Registry sebagai io.github.stackql/stackql-mcp.

tips

Bundle ini adalah salah satu dari beberapa cara untuk menjalankan server MCP StackQL. Lihat Menggunakan StackQL dengan Claude Desktop untuk panduan lengkap Claude Desktop, atau Menginstal server MCP untuk opsi npx, Docker, Python, CI, dan manual.

Menginstal server MCP​

Server MCP StackQL memungkinkan agen AI mengkueri dan menyediakan sumber daya cloud menggunakan StackQL. Server ini didistribusikan melalui beberapa saluran - semuanya menjalankan server yang sama, jadi pilih saluran yang sesuai dengan klien dan persyaratan kepercayaan Anda. Opsi di bawah ini diurutkan kira-kira berdasarkan tingkat kepercayaan dan kemudahan.

Marketplace dan direktori​

Server ini dipublikasikan ke Official MCP Registry sebagai io.github.stackql/stackql-mcp; registri paket di bawah ini memuat artefak yang dapat didistribusikan, dan direktori hilir mengambil entri tersebut dari sana.

RegistriTipeDipublikasikan melaluiEntriCatatan
Official MCP RegistryRegistri metadata kanonisCLI mcp-publisher + server.jsonmodelcontextprotocol.io/search
modelcontextprotocol.io/direct
menyatakan semua 8 paket (mcpb x5, oci, npm, pypi)
npmRegistri paketnpm publish@stackql/mcp-serverpeluncur npx
PyPIRegistri pakettwine uploadstackql-mcp-serverpeluncur uvx / pip
Docker HubRegistri containerdocker buildx --pushstackql/stackql-mcpmultiarsitektur amd64 + arm64
GitHub Actions MarketplaceMarketplace CI (action setup-stackql-mcp)Repositori publik + rilis + entri marketplacesetup-stackql-mcp-serverPenerbit terverifikasi; stackql/setup-stackql-mcp

Bundle .mcpb siap pakai​

Kapan digunakan: Claude Desktop tanpa akses ke Connector Directory, atau ketika Anda ingin mengunci versi tertentu atau memverifikasi checksum sendiri sebelum menginstal. Bagi sebagian besar pengguna Claude Desktop, Anthropic Connector Directory adalah metode instalasi yang direkomendasikan.

MCP Bundle siap pakai untuk setiap platform dilampirkan pada setiap rilis StackQL:

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

dengan <platform> salah satu dari darwin-universal, windows-x64 (AMD64), windows-arm64, linux-x64, atau linux-arm64. Tombol unduh untuk setiap platform ada di tab Claude Desktop di bagian Menggunakan dengan klien MCP. Setiap bundle memiliki checksum .sha256 yang sesuai di halaman rilis. Verifikasi checksum tersebut, lalu instal melalui Settings -> Extensions di Claude Desktop:

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

Lihat Menggunakan StackQL dengan Claude Desktop untuk panduan lengkap.

claude_desktop_config.json manual​

Kapan digunakan: biner stackql sudah ada di PATH Anda dan Anda menggunakan Claude Desktop atau klien MCP stdio lainnya.

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

Ketiga argumen ini diperlukan:

  • --mcp.server.type=stdio memilih transport stdio yang digunakan oleh klien yang tersemat di editor.
  • --approot mengarahkan cache provider ke direktori yang dapat ditulis. Klien MCP dapat meluncurkan server dengan direktori kerja yang diatur ke /, yang tidak dapat ditulis.
  • --mcp.config '{"server": {"audit": {"disabled": true}}}' menonaktifkan log audit, yang jika tidak dinonaktifkan akan menggunakan direktori kerja (yang mungkin tidak dapat ditulis) sebagai direktori default.

Tambahkan kredensial provider dengan blok "env" dan sesuaikan kontrak keamanan dengan "mode" - lihat Mode server.

npx (tanpa instalasi)​

Kapan digunakan: lingkungan Node apa pun, ketika Anda tidak ingin menginstal StackQL secara global.

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

Peluncur @stackql/mcp-server mengunduh biner stackql yang ditandatangani saat pertama kali dijalankan, memverifikasi SHA-256 biner tersebut, dan menyimpannya di cache untuk penggunaan berikutnya.

uvx / pip (Python)​

Kapan digunakan: lingkungan Python - peluncur yang sama yang dikemas untuk Python, dan berbagi cache biner yang diisi oleh peluncur npx.

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

Atau instal ke lingkungan saat ini dengan pip install stackql-mcp-server (Python 3.9+). Nama paket di PyPI adalah stackql-mcp-server.

Docker​

Kapan digunakan: runtime dalam container atau runtime terisolasi lainnya. Image ini multiarsitektur (amd64 dan arm64).

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

Sebagai konfigurasi klien:

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

Nama image di Docker Hub adalah stackql/stackql-mcp.

CI dan workflow agentik (GitHub Actions)​

Kapan digunakan: jalankan server di dalam job GitHub Actions agar agen dapat mengkueri lingkungan cloud Anda - dan, jika Anda mengizinkan, mengambil tindakan di dalamnya - sebagai bagian dari CI.

stackql/setup-stackql-mcp@v1 menginstal biner dan menulis konfigurasi MCP (secara default dalam mode read_only). Teruskan konfigurasi tersebut ke anthropics/claude-code-action melalui 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__*'

Lihat README action untuk resep agentik lainnya (audit cloud, estimasi biaya, dan sebagainya).

MCP tersemat​

Kapan digunakan: Anda sedang membangun aplikasi agentik dan ingin menyertakan server MCP ke dalam biner Anda sendiri melalui vendoring - tanpa npx, tanpa instalasi terpisah, tanpa dependensi runtime.

Library native menjalankan biner stackql yang ditandatangani melalui stdio di balik klien SDK MCP resmi setiap bahasa, sehingga aplikasi Anda mendapatkan antarmuka SQL terkendali yang sama ke setiap provider di registri. Setiap library secara default menggunakan read_only - eskalasi ke mode yang dapat menulis selalu eksplisit - dan dapat mengunduh lalu memverifikasi biner saat pertama kali dijalankan, atau menyertakannya ke dalam build Anda melalui vendoring untuk satu file executable mandiri. API lengkap per bahasa ada di referensi MCP tersemat.

Crate stackql-mcp menjalankan biner di balik klien rmcp. Fitur default sidecar mengunduh dan memverifikasi biner saat pertama kali dijalankan; fitur vendored menyematkannya dengan include_bytes! untuk satu biner mandiri. 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?;

Referensi lengkap: MCP tersemat: Rust.

Model kepercayaan​

Properti keamanan yang sama berlaku di setiap saluran:

  • Biner stackql yang tersemat ditandatangani dengan Authenticode (Windows) dan dinotarisasi oleh Apple (macOS).
  • Setiap bundle .mcpb disertai checksum SHA-256 yang dipublikasikan di halaman rilis.
  • Peluncur npx dan uvx memverifikasi SHA-256 biner yang diunduh sebelum penggunaan pertama.
  • Entri di MCP Registry mengesahkan hash per platform.

Menggunakan GitHub Actions​

GitHub Actions StackQL tersedia untuk digunakan dalam workflow GitHub Actions Anda. Action berikut tersedia:

stackql-deploy​

Gunakan StackQL untuk men-deploy atau menguji stack infrastruktur langsung dari workflow GitHub Anda. Action ini memungkinkan workflow infrastruktur sebagai kode (IaC) dengan sintaksis mirip SQL, sehingga Anda dapat mendefinisikan, men-deploy, dan mengelola sumber daya cloud di beberapa provider dalam satu workflow.


Contoh penggunaan

...
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

Library lainnya​

StackQL menyediakan beberapa metode integrasi untuk digunakan dalam berbagai bahasa pemrograman dan lingkungan. Library ini memperluas fungsionalitas StackQL, sehingga Anda dapat dengan mudah menambahkan kemampuan mengkueri dan mengelola sumber daya cloud ke aplikasi dan workflow yang sudah ada.

Paket Python pystackql​

Wrapper Python untuk menggunakan StackQL dalam program Python Anda. Paket pystackql tersedia di PyPI, dan dokumentasi paket pystackql tersedia di Read the Docs. Untuk menginstal paket pystackql, jalankan perintah berikut:

pip install pystackql

Contoh berikut menunjukkan paket pystackql yang digunakan bersama pandas untuk menjalankan kueri StackQL dan mengembalikan hasilnya ke 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)