跳到主要内容
翻译页面

本页面由 AI 辅助从英文翻译而来。如两者存在差异，以英文版本为准。

安装

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

macOS​

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

要通过 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。

下载 macOS MCPB  
下载 Linux MCPB  
下载 Windows MCPB  

信息

StackQL MCP 服务器也已收录于 Official MCP Registry，名称为 io.github.stackql/stackql-mcp。

提示

安装包是运行 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 action）公开仓库 + 发布版本 + 市场条目setup-stackql-mcp-server已验证的发布者；stackql/setup-stackql-mcp

预构建的 .mcpb 安装包​

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

更多智能体使用方案（云审计、成本估算等）请参阅 action 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?;
在 GitHub 上查看  
在 crates.io 上查看  

完整参考：嵌入式 MCP：Rust。

信任模型​

所有渠道都具备相同的安全属性：

  • 嵌入的 stackql 二进制文件经过 Authenticode 签名（Windows）和 Apple 公证（macOS）。
  • 每个 .mcpb 安装包都在发布页面上附有公开的 SHA-256 校验和。
  • npx 和 uvx 启动器在首次使用前校验所下载二进制文件的 SHA-256。
  • MCP Registry 条目为各平台的哈希值提供证明。

使用 GitHub Actions​

StackQL GitHub Actions 可在你的 GitHub Actions 工作流中使用。可用的 action 如下：

stackql-deploy​

直接在 GitHub 工作流中使用 StackQL 部署或测试基础设施堆栈。该 action 支持使用类 SQL 语法的基础设施即代码（IaC）工作流，让你可以在单个工作流中定义、部署和管理跨多个 Provider 的云资源。

在 GitHub Marketplace 上查看  
在 GitHub 上查看  

用法示例

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

以下示例展示了 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)