# 安裝

> 在 macOS、Linux、Windows、Docker 或雲端 shell 上安裝 StackQL，並從 Claude Desktop、ChatGPT、Goose 等 MCP 用戶端，或透過 npx、uvx、pip、Docker 和 GitHub Actions 使用 StackQL MCP 伺服器。

Source: https://stackql.io/zh-hant/installing-stackql

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

**macOS**

## macOS

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

**Homebrew**

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

```bash
brew install stackql
```

**curl（已簽署且經過公證的二進位檔）**

若要在目前目錄中安裝已簽署且經過公證的 `stackql` 可執行二進位檔，請在終端機中執行下列命令：

```bash
curl -fsSL https://get-stackql.io/install | sh
```

**套件下載**

StackQL 提供適用於 macOS、已簽署且經過公證的互動式 `pkg` 安裝程式。

[下載 macOS PKG](https://releases.stackql.io/stackql/latest/stackql_darwin_multiarch.pkg)

**Linux**

## Linux

StackQL 適用於所有 Linux 架構。

**curl**

若要在目前目錄中安裝適用於您的 Linux 架構（amd64 或 arm64）的 `stackql` 可執行二進位檔，請在終端機中執行下列命令：

```bash
curl -fsSL https://get-stackql.io/install | sh
```

**套件下載**

您也可以在這裡下載二進位檔：

[下載 Linux ZIP（amd64）](https://releases.stackql.io/stackql/latest/stackql_linux_amd64.zip)
[下載 Linux ZIP（arm64）](https://releases.stackql.io/stackql/latest/stackql_linux_arm64.zip)

**Windows**

## Windows

在 Windows 上可以透過 Chocolatey、PowerShell 安裝指令碼和 MSI 安裝程式取得 StackQL。原生 AMD64（x64）和 ARM64 建置以 MSI 安裝程式和包含 `stackql.exe` 的 ZIP 封存檔形式提供。AMD64 建置也可以透過模擬在 ARM64 上執行。所有可執行檔都以 Authenticode 程式碼簽署憑證簽署。

**Chocolatey**

若要透過 Chocolatey 安裝，請在 PowerShell 或 `cmd` 終端機中執行下列命令：

```powershell
choco install stackql
```

**Invoke-RestMethod**

若要在目前目錄中安裝 Authenticode 可執行檔，請在 PowerShell 終端機中執行下列命令： 

```powershell
Invoke-RestMethod https://get-stackql.io/install | Invoke-Expression
# or
irm https://get-stackql.io/install | iex
```

**MSI/ZIP 下載**

請從下方下載已簽署的 Windows `stackql` 安裝程式或可執行檔。按一下下載按鈕預設會選取 AMD64；使用按鈕的下拉式選單可選擇 AMD64 或原生 ARM64。

[下載 Windows MSI](https://releases.stackql.io/stackql/latest/stackql_windows_amd64.msi)
[下載 Windows ZIP](https://releases.stackql.io/stackql/latest/stackql_windows_amd64.zip)

**Docker**

## Docker

StackQL 建置會發佈到 [Docker Hub](https://hub.docker.com/u/stackql)。  

__Docker Hub__  

若要提取 StackQL 容器映像檔，請執行下列命令：

```bash
docker pull stackql/stackql
```

從 `v1.0` 起，映像檔以 Ubuntu 26.04 LTS 為基礎，另有預先安裝 Python 3.13 的變體，以 `-python3.13` 標籤尾碼（別名 `-python3`）發佈，例如：

```bash
docker pull stackql/stackql:latest-python3.13
```

**stackql-deploy**

## `stackql-deploy`

`stackql-deploy` 是以 StackQL 為基礎建置的無狀態 IaC 架構。完整文件請參閱 [**StackQL Deploy 文件**](https://stackql-deploy.io/)。

__Linux / macOS__

一個步驟即可下載並解壓縮最新的 `stackql-deploy` 二進位檔。安裝程式會偵測您的作業系統和架構（包括透過通用 macOS 二進位檔支援的 Apple Silicon 和 Intel），並自動取得正確的發行版本資產。
```bash
curl -fsSL https://get-stackql-deploy.io/install.sh | sh
```

__Windows__

將最新的 `stackql-deploy` 二進位檔下載並解壓縮到目前目錄。安裝程式會偵測您的平台，並自動取得正確的發行版本資產。
```powershell
irm https://get-stackql-deploy.io/install.ps1 | iex
```

__cargo__

如果您已安裝 Rust 工具鏈，此命令會直接從 [__crates.io__](https://crates.io/crates/stackql-deploy) 建置並安裝二進位檔。
```bash
cargo install stackql-deploy
```

**雲端 shell**

## 雲端 shell

StackQL 可以直接在主要雲端和資料平台內建的雲端 shell 與網頁終端機中使用。這些環境已預先以您登入的身分完成授權，因此能提供順暢的體驗，不需要另外設定驗證。

**AWS**

### AWS CloudShell

AWS CloudShell 提供以瀏覽器為基礎的 shell，已預先安裝 AWS CLI 並完成驗證。在 AWS CloudShell 中執行 StackQL，您不需要額外的驗證步驟，即可查詢和管理 AWS 資源。如需詳細說明，請參閱我們的 [AWS CloudShell 教學](/quick-starts/aws/aws-cloud-shell)。

首先，下載 StackQL 套件：

```bash
curl -fsSL https://get-stackql.io/install/aws | sh
```
然後執行 StackQL AWS CloudShell 指令碼：

```bash
./stackql-aws-cloud-shell.sh
```  

此指令碼會使用您的 AWS CloudShell 憑證啟動 StackQL 命令 shell，讓您可以立即開始查詢 AWS 資源。

**Azure**

### Azure Cloud Shell

Azure Cloud Shell 提供可從瀏覽器存取的 shell 環境，其中的 Azure CLI 已使用您的 Azure 帳戶預先完成驗證。在 Azure Cloud Shell 中使用 StackQL，不需要額外設定即可順暢查詢您的 Azure 資源。如需完整詳細資訊，請參閱我們的 [Azure Cloud Shell 指南](/blog/tutorials/using-stackql-in-native-cloud-shells-in-aws-azure-and-gcp#using-stackql-in-the-azure-cloud-shell)。  

首先，下載 StackQL 套件：

```bash
curl -fsSL https://get-stackql.io/install/azure | sh
```

然後執行 StackQL Azure Cloud Shell 指令碼：

```bash
./stackql-azure-cloud-shell.sh
```

此指令碼會自動設定 StackQL 工作階段以使用您的 Azure Cloud Shell 憑證，讓您可以立即存取並查詢 Azure 資源。

**Google**

### Google Cloud Shell

Google Cloud Shell 提供開發與維運環境，其中的 Google Cloud CLI 已完成驗證。在 Google Cloud Shell 中執行 StackQL，您可以使用現有的驗證查詢 GCP 資源。如需詳細資訊，請參閱我們的 [Google Cloud Shell 指南](/blog/tutorials/using-stackql-in-native-cloud-shells-in-aws-azure-and-gcp#using-stackql-in-the-google-cloud-shell)。  

首先，下載 StackQL 套件：

```bash
curl -fsSL https://get-stackql.io/install/google | sh
```

然後執行 StackQL Google Cloud Shell 指令碼：

```bash
./stackql-google-cloud-shell.sh
```

此指令碼會將 StackQL 設定為使用您的 Google Cloud Shell 憑證，讓您可以立即開始使用 SQL 語法查詢 GCP 資源。

**Databricks**

### Databricks Web Terminal

Databricks 工作區包含一個以登入使用者身分執行的網頁終端機。在其中執行 StackQL，您可以使用您的 Databricks 身分查詢工作區，不需要另外設定驗證。如需查詢範例和帳戶層級驗證，請參閱我們的 [Databricks Web Terminal 指南](/blog/tutorials/stackql-in-databricks-web-terminal)。

首先，下載 StackQL 套件：

```bash
curl -fsSL https://get-stackql.io/install/databricks | sh
```

然後執行 StackQL Databricks shell 指令碼：

```bash
./stackql-databricks-shell.sh
```

這會使用您的 Databricks 工作區身分啟動 StackQL 工作階段，讓您可以立即查詢工作區範圍的資源，例如 `databricks_workspace.iam.vw_user_entitlements`。若要執行帳戶層級查詢（佈建、計費、帳戶 IAM），請依照指南中的說明設定 Databricks OAuth2 服務主體變數。

## 搭配 MCP 用戶端使用

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

**Claude Desktop**

### Claude Desktop

  將 StackQL MCP 伺服器安裝到 Claude Desktop 的建議方式是透過 [Anthropic Connector Directory](https://claude.ai/directory/connectors/ant.dir.gh.stackql.stackql)（**Settings -> Connectors -> Add -> Browse Connectors**，搜尋 **StackQL**），Claude Desktop 會自動為您的平台選取正確的已簽署二進位檔。此外，每個 StackQL 發行版本都附有預先建置的 MCP Bundle（`.mcpb`），可從下載的檔案安裝。無論採用哪種方式，都不需要另外安裝 StackQL。安裝套件提供 macOS、Windows 和 Linux 版本。

  Linux 和 Windows 的 MCPB 下載預設為 **amd64**（x64）。使用下拉式選單可選取 **amd64** 或 **arm64**。

  [下載 macOS MCPB](https://releases.stackql.io/stackql/latest/stackql-mcp-darwin-universal.mcpb)
[下載 Linux MCPB](https://releases.stackql.io/stackql/latest/stackql-mcp-linux-x64.mcpb)
[下載 Windows MCPB](https://releases.stackql.io/stackql/latest/stackql-mcp-windows-x64.mcpb)

:::info

StackQL MCP 伺服器也以 `io.github.stackql/stackql-mcp` 名稱列於 [__Official MCP Registry__](https://registry.modelcontextprotocol.io/v0/servers?search=stackql)。

:::

:::tip

安裝套件是執行 StackQL MCP 伺服器的數種方式之一。如需完整的 Claude Desktop 逐步解說，請參閱[**在 Claude Desktop 中使用 StackQL**](/getting-started/claude-desktop)；如需 npx、Docker、Python、CI 和手動選項，請參閱[**安裝 MCP 伺服器**](#installing-the-mcp-server)。

:::

**ChatGPT**

### ChatGPT 和 Codex

  StackQL 以本機外掛程式的形式提供給 ChatGPT 桌面應用程式和 Codex CLI。此外掛程式透過 stdio 在您的電腦上執行 StackQL MCP 伺服器，因此 Provider 憑證不會離開您的電腦。需要 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 mode 中、在您電腦上執行的對話串中提供。如果您的目錄中尚未顯示此清單項目，請改從存放庫市集安裝。

  **ChatGPT 桌面應用程式（存放庫市集）**：  

  開啟 **Settings -> Plugins -> Add -> Add from GitHub**，輸入 `stackql/stackql`，然後從外掛程式目錄的 **Personal** 區段安裝 **StackQL**，並重新啟動應用程式。

  **Codex CLI**：

  ```shell
  codex plugin marketplace add stackql/stackql --sparse .agents/plugins --sparse packaging/openai-plugin
  codex plugin add stackql@stackql
  ```

  重新啟動 ChatGPT 桌面版或 Codex，然後嘗試：*使用 StackQL 安裝 GitHub Provider（如有需要），然後列出前五個 GitHub 服務。* Provider 憑證放在 `~/.stackql/.env` 中，並使用各 Provider 的標準環境變數名稱（例如 `AWS_ACCESS_KEY_ID` 和 `AWS_SECRET_ACCESS_KEY`）；編輯該檔案後，請要求代理程式呼叫 `reload_credentials`。

  **不使用外掛程式**：   

  在 **Settings -> Plugins -> MCPs -> Connect to a custom MCP** 下，選擇 **STDIO**，將命令設為 `npx`，並新增引數 `-y` 和 `@stackql/mcp-server`。在該表單上以環境變數提供 Provider 憑證。

:::note

ChatGPT 網頁版和行動版無法執行本機 stdio 伺服器，因此此外掛程式僅適用於桌面版和 Codex。ChatGPT 桌面版一個尚未修正的錯誤（[openai/codex#38162](https://github.com/openai/codex/issues/38162)）可能會在 **Chat** 工作階段中隱藏本機 MCP 工具；Work mode 對話串、Codex 對話串和 Codex CLI 不受影響。

:::

**Goose**

### Goose

  Goose 會直接執行 stdio 擴充功能，因此您只需要 `npx` 啟動器（Node.js 24.22.1 或更新版本，在對應的發行線上為 22.23.4 或 26.12.1）。

  **Goose Desktop**：按一下下方按鈕。Goose 會開啟，顯示即將執行的命令並要求您確認，然後將 StackQL 新增為擴充功能。

  在 Goose Desktop 中安裝

  此按鈕是 `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**：

  ```shell
  goose session --with-extension "npx -y @stackql/mcp-server"
  ```

  或執行 `goose configure`，選擇 **Add Extension -> Command-line Extension**，然後輸入相同的命令。出現提示時，以擴充功能的環境變數提供 Provider 憑證。

:::note

Goose 已停用應用程式內的擴充功能目錄，改用 [Official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=stackql)，StackQL 在其中以 `io.github.stackql/stackql-mcp` 列出。Goose 推出登錄庫匯入功能後，不需要任何額外動作，即可在其中找到 StackQL。

:::

## 安裝 MCP 伺服器

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

### 市集和目錄

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

**登錄庫**

| 登錄庫 | 類型 | 發佈方式 | 清單項目 | 備註 |
|---|---|---|---|---|
| Official MCP Registry | 標準中繼資料登錄庫 | `mcp-publisher` CLI + `server.json` | [`modelcontextprotocol.io/search`](https://registry.modelcontextprotocol.io/v0/servers?search=stackql) [`modelcontextprotocol.io/direct`](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.stackql/stackql-mcp) | 宣告全部 8 個套件（`mcpb x5`、`oci`、`npm`、`pypi`） |
| npm | 套件登錄庫 | `npm publish` | [`@stackql/mcp-server`](https://www.npmjs.com/package/@stackql/mcp-server) | `npx` 啟動器 |
| PyPI | 套件登錄庫 | `twine upload` | [`stackql-mcp-server`](https://pypi.org/project/stackql-mcp-server/) | `uvx` / `pip` 啟動器 |
| Docker Hub | 容器登錄庫 | `docker buildx --push` | [`stackql/stackql-mcp`](https://hub.docker.com/r/stackql/stackql-mcp) | 多架構 `amd64` + `arm64` |
| GitHub Actions Marketplace | CI 市集（`setup-stackql-mcp` 動作） | 公開存放庫 + 發行版本 + 市集清單項目 | [`setup-stackql-mcp-server`](https://github.com/marketplace/actions/setup-stackql-mcp-server) | 已驗證的發行者；[`stackql/setup-stackql-mcp`](https://github.com/stackql/setup-stackql-mcp) |

**目錄**

目錄和彙總網站清單項目，大致依對探索的重要性排序：

| 目錄 | 類型 | 清單項目 |
|---|---|---|
| __Anthropic Connector Directory__ | Claude Desktop 應用程式內目錄 | [claude.ai/directory](https://claude.ai/directory/connectors/ant.dir.gh.stackql.stackql) |
| __OpenAI Plugin Directory__ | ChatGPT 桌面應用程式內目錄（僅限桌面版） | 在 ChatGPT 桌面應用程式中搜尋 **StackQL**；請參閱 [ChatGPT 和 Codex](#using-with-mcp-clients) |
| __Cursor Directory__ | IDE 用戶端目錄 | [cursor.directory](https://cursor.directory/plugins/stackql-mcp-server) |
| __mcp.so__ | 最大的彙總網站 | [mcp.so](https://mcp.so/server/stackql/stackql) |
| __PulseMCP__ | 探索服務、登錄庫贊助者 | [pulsemcp](https://www.pulsemcp.com/servers/stackql) |
| __Glama.ai MCP__ | 可搜尋的市集 | [glama.ai](https://glama.ai/mcp/servers/stackql/stackql) |
| __mcpmarket.com__ | 彙總網站 | [mcpmarket](https://mcpmarket.com/server/stackql) |
| __mcpservers.org__ | Awesome-list 網站 | [mcpservers.org](https://mcpservers.org/servers/stackql-mcp-server) |

### 預先建置的 `.mcpb` 安裝套件

**適用情境**：無法存取 Connector Directory 的 Claude Desktop，或您想要固定特定版本，或在安裝前自行驗證總和檢查碼時。對於大多數 Claude Desktop 使用者，建議的安裝方式是 [Anthropic Connector Directory](https://claude.ai/directory/connectors/ant.dir.gh.stackql.stackql)。

每個 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 用戶端使用](#using-with-mcp-clients)下的 **Claude Desktop** 索引標籤中。每個安裝套件在[發行版本頁面](https://github.com/stackql/stackql/releases/latest)上都有對應的 `.sha256` 總和檢查碼。驗證後，再透過 Claude Desktop 中的 **Settings -> Extensions** 安裝：

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

如需完整的逐步解說，請參閱[在 Claude Desktop 中使用 StackQL](/getting-started/claude-desktop#install-from-a-downloaded-bundle)。

### 手動設定 `claude_desktop_config.json`

**適用情境**：您的 PATH 中已有 `stackql` 二進位檔，並使用 Claude Desktop 或任何其他 stdio MCP 用戶端。

```json
{
  "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"` 調整安全契約。請參閱[伺服器模式](/command-line-usage/mcp#server-modes)。

### `npx`（免安裝）

**適用情境**：任何 Node 環境，且您不想全域安裝 StackQL 時。

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

[`@stackql/mcp-server`](https://www.npmjs.com/package/@stackql/mcp-server) 啟動器會在首次執行時下載已簽署的 `stackql` 二進位檔，驗證其 SHA-256，並將其快取以供後續執行使用。

### `uvx` / `pip` (Python)

**適用情境**：Python 環境。這是為 Python 封裝的同一個啟動器，與 npx 啟動器共用其填入的二進位檔快取。

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

或使用 `pip install stackql-mcp-server` 將其安裝到目前的環境中（Python 3.9+）。此套件在 PyPI 上為 [`stackql-mcp-server`](https://pypi.org/project/stackql-mcp-server/)。

### Docker

**適用情境**：容器化或其他隔離的執行環境。此映像檔支援多架構（amd64 和 arm64）。

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

作為用戶端設定：

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

此映像檔在 Docker Hub 上為 [`stackql/stackql-mcp`](https://hub.docker.com/r/stackql/stackql-mcp)。

### CI 和代理式工作流程（GitHub Actions）

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

[`stackql/setup-stackql-mcp@v1`](https://github.com/marketplace/actions/setup-stackql-mcp-server) 會安裝二進位檔並寫入 MCP 設定（預設為 `read_only` 模式）。透過 `claude_args` 將該設定傳遞給 [`anthropics/claude-code-action`](https://github.com/anthropics/claude-code-action)：

```yaml
- 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](https://github.com/stackql/setup-stackql-mcp)。

### 內嵌式 MCP

**適用情境**：您正在建置代理式應用程式，並想將 MCP 伺服器 vendor 到您自己的二進位檔中：不需要 `npx`、不需要另外安裝，也沒有執行階段相依性。

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

**Rust**

`stackql-mcp` crate 會在 `rmcp` 用戶端背後啟動二進位檔。預設的 `sidecar` 功能會在首次執行時下載並驗證二進位檔；`vendored` 功能則使用 `include_bytes!` 將其內嵌，以產生單一獨立的二進位檔。MSRV 為 Rust 1.88。

```toml
# Cargo.toml
stackql-mcp = "0.1"
```

```rust
use stackql_mcp::{Mode, StackqlMcp};

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

[在 GitHub 上檢視](https://github.com/stackql/stackql-mcp-rs)
[在 crates.io 上檢視](https://crates.io/crates/stackql-mcp)

完整參考：[內嵌式 MCP：Rust](/mcp/embedded/rust)。

**Go**

`stackql-mcp-go` 程式庫會在官方 Go MCP SDK 用戶端背後啟動二進位檔。使用 `go:embed` vendor 二進位檔可產生單一獨立的二進位檔，也可以讓它在首次執行時下載並驗證。預設以 `read_only` 模式啟動。

```bash
go get github.com/stackql/stackql-mcp-go
```

```go
import (
    "context"
    stackqlmcp "github.com/stackql/stackql-mcp-go/embed"
)

client, err := stackqlmcp.StartServer(ctx, stackqlmcp.Options{
    Binary: StackqlMCPBinary(),
})
defer client.Close()
```

[在 GitHub 上檢視](https://github.com/stackql/stackql-mcp-go)
[在 pkg.go.dev 上檢視](https://pkg.go.dev/github.com/stackql/stackql-mcp-go)

完整參考：[內嵌式 MCP：Go](/mcp/embedded/go)。

**Kotlin / JVM**

`io.stackql:stackql-mcp` 程式庫會在官方 Kotlin MCP SDK 用戶端背後啟動二進位檔，另有一個配套的 Gradle 外掛程式，可將相同的啟動方式接入建置。需要 JDK 17 和 Kotlin 2.x。

```kotlin
dependencies {
    implementation("io.stackql:stackql-mcp:0.1.0")
}
```

```kotlin
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
}
```

[在 GitHub 上檢視](https://github.com/stackql/stackql-mcp-kotlin)

完整參考：[內嵌式 MCP：Kotlin / JVM](/mcp/embedded/kotlin)。

**.NET**

`StackQL.Mcp` 套件會在官方 C# MCP SDK 用戶端背後啟動二進位檔。預設採用 sidecar 方式，也可以將安裝套件作為建置資源 vendor，以產生獨立的可執行檔。需要 .NET 8 或更新版本。

```bash
dotnet add package StackQL.Mcp
```

```csharp
using StackQL.Mcp;

await using var server = await StackqlMcp.CreateBuilder()
    .WithMode(StackqlMode.ReadOnly)
    .StartAsync();

var tools = await server.ListToolsAsync();
```

[在 GitHub 上檢視](https://github.com/stackql/stackql-mcp-dotnet)

完整參考：[內嵌式 MCP：.NET / C#](/mcp/embedded/dotnet)。

**Gleam**

`stackql_mcp` 程式庫以 Erlang/BEAM 執行階段為目標，並透過 `child_spec()` 將伺服器公開為 OTP 子處理程序，因此可以放在您自己的監督樹中。預設以 `read_only` 模式啟動。

```bash
gleam add stackql_mcp
```

```gleam
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)
```

[在 GitHub 上檢視](https://github.com/stackql/stackql-mcp-gleam)

完整參考：[內嵌式 MCP：Gleam](/mcp/embedded/gleam)。

**Swift**

`stackql-mcp-swift` 套件會在官方 Swift MCP SDK 用戶端背後啟動二進位檔。`darwin-universal` 二進位檔已使用 Developer ID 簽署並經過 Apple 公證，因此您可以將它封裝在已簽署的 `.app` 中，同時維持應用程式的公證有效。需要 macOS 13+ 和 Swift 6.1（Xcode 16.3+）。

```swift
// Package.swift
.package(url: "https://github.com/stackql/stackql-mcp-swift.git", from: "0.1.0")
```

```swift
import StackQLMCP

var options = Options()
options.mode = .readOnly

let server = try await StackQLServer.start(options)
let tools = try await server.listToolNames()
await server.stop()
```

[在 GitHub 上檢視](https://github.com/stackql/stackql-mcp-swift)

完整參考：[內嵌式 MCP：Swift](/mcp/embedded/swift)。

### 信任模型

所有通道都具備相同的安全屬性：

- 內嵌的 `stackql` 二進位檔已使用 Authenticode 簽署（Windows）並經過 Apple 公證（macOS）。
- 每個 `.mcpb` 安裝套件在發行版本頁面上都附有公開的 SHA-256 總和檢查碼。
- `npx` 和 `uvx` 啟動器會在首次使用前驗證所下載二進位檔的 SHA-256。
- [MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=stackql) 項目會為各平台的雜湊提供證明。

## 使用 GitHub Actions

[StackQL GitHub Actions](https://github.com/stackql/stackql-actions-demo) 可在您的 GitHub Actions 工作流程中使用。提供下列動作：

**stackql-deploy**

### `stackql-deploy`

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

[在 GitHub Marketplace 上檢視](https://github.com/marketplace/actions/stackql-deploy)
[在 GitHub 上檢視](https://github.com/stackql/stackql-deploy-action)

**範例用法**

```yaml
...
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**

### `setup-stackql`

在您的 GitHub Actions 工作流程中設定 StackQL。  

[在 GitHub Marketplace 上檢視](https://github.com/marketplace/actions/setup-stackql)
[在 GitHub 上檢視](https://github.com/stackql/setup-stackql)

**範例用法**

```yaml
- 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**

### `setup-stackql-mcp`

在您的 GitHub Actions 工作流程中安裝 StackQL MCP 伺服器。此動作會安裝已簽署的二進位檔，並寫入 `mcpServers` 設定（預設為 `read_only` 模式），供 `anthropics/claude-code-action` 等代理式步驟透過 `claude_args` 使用。

[在 GitHub Marketplace 上檢視](https://github.com/marketplace/actions/setup-stackql-mcp-server)
[在 GitHub 上檢視](https://github.com/stackql/setup-stackql-mcp)

**範例用法**

```yaml
- 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**

### `stackql-exec`

在您的 GitHub Actions 工作流程中執行 StackQL 命令。查詢可以內嵌提供，或來自存放庫中的檔案。  

[在 GitHub Marketplace 上檢視](https://github.com/marketplace/actions/stackql-exec)
[在 GitHub 上檢視](https://github.com/stackql/stackql-exec)

**範例用法**

```yaml
- 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**

### `stackql-assert`

在您的 GitHub Actions 工作流程中執行單元測試（用於保證、治理或雲端安全性檢查）。  

[在 GitHub Marketplace 上檢視](https://github.com/marketplace/actions/stackql-assert)
[在 GitHub 上檢視](https://github.com/stackql/stackql-assert)

**範例用法**

```yaml
- 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__](https://pypi.org/project/pystackql/) 取得，`pystackql` 套件的文件可透過 [__Read the Docs__](https://pystackql.readthedocs.io/en/latest/) 取得。若要安裝 `pystackql` 套件，請執行下列命令：

```bash
pip install pystackql
```

下列範例示範如何搭配 `pandas` 使用 `pystackql` 套件來執行 StackQL 查詢，並將結果傳回至 `pandas.DataFrame`：

```python
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)
```
