跳至主要內容
翻譯頁面

本頁面由英文在 AI 協助下翻譯而成。若兩者有出入,請以英文版本為準。

安裝

這裡提供在各種不同平台上安裝 StackQL 的說明。

macOS​

在 macOS 上可以透過 Homebrew 和 pkg 安裝程式取得 StackQL,單一多架構安裝程式同時支援 ARM(M1/Apple Silicon)和 Intel(x86_64)架構。

若要透過 Homebrew 安裝,請在終端機中執行下列命令:

brew install stackql

搭配 MCP 用戶端使用​

StackQL MCP 伺服器透過 stdio 在本機執行,因此無論您使用哪個用戶端,Provider 憑證都會留在您的電腦上。請在下方選擇您的用戶端:每個索引標籤會先提供目錄或一鍵安裝方式,再提供手動設定作為備用方案。如需所有發佈通道(包括 npx、Python、Docker 和 CI),請參閱安裝 MCP 伺服器。

Claude Desktop​

將 StackQL MCP 伺服器安裝到 Claude Desktop 的建議方式是透過 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 伺服器也以 io.github.stackql/stackql-mcp 名稱列於 Official MCP Registry。

提示

安裝套件是執行 StackQL MCP 伺服器的數種方式之一。如需完整的 Claude Desktop 逐步解說,請參閱在 Claude Desktop 中使用 StackQL;如需 npx、Docker、Python、CI 和手動選項,請參閱安裝 MCP 伺服器。

安裝 MCP 伺服器​

StackQL MCP 伺服器可讓 AI 代理程式使用 StackQL 查詢和佈建雲端資源。它透過多種通道發佈,這些通道都執行相同的伺服器,因此請選擇符合您的用戶端和信任需求的通道。下列選項大致依信任程度和易用性排序。

市集和目錄​

此伺服器以 io.github.stackql/stackql-mcp 發佈至 Official MCP Registry;下列套件登錄庫提供可散發的成品,下游目錄則從這些來源取得清單項目。

登錄庫類型發佈方式清單項目備註
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​

適用情境:您的 PATH 中已有 stackql 二進位檔,並使用 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 將 Provider 快取指向可寫入的目錄。MCP 用戶端可能會在工作目錄設為 / 的情況下啟動伺服器,而該目錄無法寫入。
  • --mcp.config '{"server": {"audit": {"disabled": true}}}' 會停用稽核記錄;否則稽核記錄的目錄預設為(可能無法寫入的)工作目錄。

使用 "env" 區塊新增 Provider 憑證,並使用 "mode" 調整安全契約。請參閱伺服器模式。

npx(免安裝)​

適用情境:任何 Node 環境,且您不想全域安裝 StackQL 時。

{ "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)​

適用情境:在 GitHub Actions 作業中執行伺服器,讓代理程式能在 CI 中查詢您的雲端,並在您允許時對其採取動作。

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 伺服器 vendor 到您自己的二進位檔中:不需要 npx、不需要另外安裝,也沒有執行階段相依性。

原生程式庫在各語言官方 MCP SDK 用戶端背後,透過 stdio 啟動已簽署的 stackql 二進位檔,讓您的應用程式透過同一套受治理的 SQL 介面存取登錄庫中的每個 Provider。每個程式庫預設為 read_only(提升為可寫入模式一律需要明確指定),並且可以在首次執行時下載並驗證二進位檔,或將其 vendor 到您的建置中,以產生單一獨立的可執行檔。完整的各語言 API 請參閱內嵌式 MCP 參考。

stackql-mcp crate 會在 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​

StackQL GitHub Actions 可在您的 GitHub Actions 工作流程中使用。提供下列動作:

stackql-deploy​

直接從您的 GitHub 工作流程使用 StackQL 部署或測試基礎架構堆疊。此動作支援使用類 SQL 語法的基礎架構即程式碼(IaC)工作流程,讓您能在單一工作流程中定義、部署和管理跨多個 Provider 的雲端資源。


範例用法

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

下列範例示範如何搭配 pandas 使用 pystackql 套件來執行 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)