# 安装

> 在 macOS、Linux、Windows、Docker 或云 shell 中安装 StackQL，并在 Claude Desktop、ChatGPT、Goose 等 MCP 客户端中，或通过 npx、uvx、pip、Docker 和 GitHub Actions 使用 StackQL MCP 服务器。

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

本页提供在各种平台上安装 StackQL 的说明。

**macOS**

## macOS

StackQL 在 macOS 上可通过 Homebrew 和 `pkg` 安装程序获取，单个多架构安装程序同时支持 ARM（M1/Apple Silicon）和 AMD 架构。

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

StackQL 在 Windows 上可通过 Chocolatey、PowerShell 安装脚本和 MSI 安装程序获取。原生 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 构建版本发布到 [DockerHub](https://hub.docker.com/u/stackql)。  

__Docker Hub__  

要拉取 StackQL 容器镜像，请运行以下命令：

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

从 `v1.0` 起，该镜像基于 Ubuntu 26.04 LTS，并以 `-python3.13` 标签后缀（别名 `-python3`）发布预装 Python 3.13 的变体，例如：

```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 和 Web 终端中使用。这些环境已使用你登录的身份预先授权，无需单独设置身份验证，因此使用体验顺畅。

**AWS**

### AWS Cloud Shell

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 终端

Databricks 工作区包含以当前登录用户身份运行的 Web 终端。在其中运行 StackQL，可以使用你的 Databricks 身份查询工作区，无需单独设置身份验证。示例查询和账号级身份验证请参阅 [Databricks Web 终端指南](/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 服务器也已收录于 [__Official MCP Registry__](https://registry.modelcontextprotocol.io/v0/servers?search=stackql)，名称为 `io.github.stackql/stackql-mcp`。

:::

:::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 模式下、在你的计算机上运行的线程中可用。如果该条目尚未出现在你的目录中，请改为从仓库市场安装。

  **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，然后列出前 5 个 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 桌面应用的一个未修复 bug（[openai/codex#38162](https://github.com/openai/codex/issues/38162)）可能导致本地 MCP 工具在 **Chat** 会话中不可见；Work 模式线程、Codex 线程和 Codex CLI 不受影响。

:::

**Goose**

### Goose

  Goose 直接运行 stdio 扩展，因此只需要 `npx` 启动器（Node.js 18 或更高版本）。

  **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` action） | 公开仓库 + 发布版本 + 市场条目 | [`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 列表站点 | [mcpservers.org](https://mcpservers.org/servers/stackql-mcp-server) |

### 预构建的 `.mcpb` 安装包

**适用场景：** Claude Desktop 无法访问 Connector Directory，或者希望固定到特定版本，或在安装前自行验证校验和。对于大多数 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`

**适用场景：** `stackql` 二进制文件已在你的 PATH 中，并且使用 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__*'
```

更多智能体使用方案（云审计、成本估算等）请参阅 [action 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 工作流中使用。可用的 action 如下：

**stackql-deploy**

### `stackql-deploy`

直接在 GitHub 工作流中使用 StackQL 部署或测试基础设施堆栈。该 action 支持使用类 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 服务器。该 action 安装已签名的二进制文件并写入 `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
```

以下示例展示了 `pystackql` 软件包与 `pandas` 配合使用，运行 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)
```