stackql/stackql · 上手攻略

• 仓库：stackql/stackql
• 链接：https://github.com/stackql/stackql
• 分类：云资源查询 / MCP server / SQL engine
• 作者：spark
• 更新：2026-09-07

⚠️ 本文写作日期 2026-09-07。MCP server 功能自 StackQL 0.9.250 起可用(来源:StackQL 官方博客 "StackQL MCP Server Now Available")。所有命令与字段以本文抓取时(2026-09-07 07:33 UTC)的 README 与官方文档为准;版本细节请以 https://github.com/stackql/stackql/releases 为准。

1. 是什么

StackQL 是一个 Go 写的多云统一 SQL 引擎:用 SQL 语法查询、变更、运维 Cloud / SaaS / API / MCP 资源,内置 Provider Registry(由各 provider 的 OpenAPI spec 扩展生成),把 REST API 调用编译成 SQL 结果。README 原文:

"StackQL is an open-source project built with Golang that allows you to create, modify and query the state of services and resources across different local and remote interfaces, using SQL semantics. Such interfaces canonically include, but are not limited to, cloud and SaaS providers (Google, AWS, Azure, Okta, GitHub, etc.)."

自 0.9.250 起,它本身是一个 MCP server,面向 Claude / VS Code / Cursor 等 MCP client 用 SQL 跨 40+ provider 操作资源(README 与 mcpservers.org 双源核实)。

2. 解决什么问题

四个常见痛点:

1. 多云异构:AWS/GCP/Azure/Okta/GitHub 等各有 CLI 和 API,跨云聚合资产或做对照查询要写 N 段脚本。
2. AI agent 难直接运维云:agent 需要一种"稳定的、结构化的、可被 prompt 调用的接口"。StackQL 把 provider API 抽象成 SQL schema,agent 可以用 SELECT/INSERT/UPDATE/DELETE 表达意图。
3. IaC 审计 / 资产盘点:临时要列"所有 region 下未挂载的 EBS"或"过去 7 天创建的 IAM 用户",要么写脚本,要么接 Athena / Steampipe。
4. Postgres 协议兼容:用 stackql srv 起一个 Postgres wire protocol server,psycopg2 / psql / 任何 Postgres 客户端都能连(README 明示)。

定位一句话:用 SQL 把 40+ 云 / SaaS / API 资源"装进"一个 schema,人写也方便、AI agent 调也方便。

3. 快速安装

3.1 macOS

# Homebrew(amd64 + arm64)
brew install stackql
# 或显式 tap
brew tap stackql/tap && brew install stackql/tap/stackql

# PKG 安装器(amd64 + arm64)
curl -O https://storage.googleapis.com/stackql-public-releases/latest/stackql_darwin_multiarch.pkg
# 双击或 sudo installer -pkg stackql_darwin_multiarch.pkg -target /

3.2 Windows

# MSI 安装器
curl -O https://releases.stackql.io/stackql/latest/stackql_windows_amd64.msi
# 双击安装,或 msiexec /i stackql_windows_amd64.msi /qn

# Chocolatey
choco install stackql

# 或下 ZIP 解压到任意目录,把目录加进 PATH
curl -O https://releases.stackql.io/stackql/latest/stackql_windows_amd64.zip

3.3 Linux

# ZIP + 一行短链
curl -L https://bit.ly/stackql-zip -O && unzip stackql-zip
# 把 stackql 二进制加到 PATH

3.4 Docker

docker pull stackql/stackql

README 强调:StackQL does not require or install a database(即使是 Postgres 协议模式也是它自己当 server,不依赖外部 Postgres)。

4. 核心用法

4.1 三种运行模式(README 原文)

模式	命令	用途
Interactive shell	stackql shell --auth="${AUTH}"	交互式 REPL
Exec(单条/文件)	stackql exec --auth="${AUTH}" -i myscript.iql --iqldata vars.js	批处理 / CI
Server(Postgres 协议)	stackql srv ...	当 Postgres 监听,psycopg2 / 任何 PG 客户端直连

4.2 Provider Registry 与 schema 生成

• provider 定义在独立仓库 stackql-provider-registry,由各 provider 的 OpenAPI spec 扩展而来。
• SDK 层在 stackql/any-sdk,负责 provider 交互语义。
• 本仓库(stackql/stackql)是应用本体,把 provider 定义解析成 SQL schema 与 API client。

4.3 MCP server 用法(0.9.250+)

README 给出四种客户端分发:stdin / npm(npx) / PyPI(uvx) / Docker / .mcpb bundle / GitHub Action。挑自己习惯的:

npm(npx)——~/.config/claude_desktop_config.json 或 VS Code/Cursor 的 MCP 配置里:

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

PyPI(uvx):

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

Docker:

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

.mcpb bundle(原生 GUI 客户端一键安装):https://github.com/stackql/stackql/releases/latest 拉对应平台 bundle(stackql-mcp-linux-x64.mcpb / -linux-arm64.mcpb / -windows-x64.mcpb / -darwin-universal.mcpb)。

GitHub Actions(默认 read_only,CI 安全默认):

- uses: stackql/setup-stackql-mcp@v1
  with:
    mode: read_only

4.4 用 stdio 跑(本地裸跑)

stackql mcp --mcp.server.type=stdio

io.github.stackql/stackql-mcp 已收录到 Official MCP Registry(README 明示)。

4.5 一个典型的 SQL 风格调用(README 模式,字段以仓库 docs/ 为准)

-- 列出某 region 下所有 EC2 实例的 id / type / state
SELECT id, instanceType, state
FROM aws.ec2.instances
WHERE region = 'us-east-1';

写多 provider 联查也是 SQL 原生语法(具体跨 provider JOIN 支持度以官方 docs 为准,本文不展开不确定语法)。

4.6 一键只读安全审计

README 提到 Docker audit quickstart(docs/audit.md):"read-only cross-cloud security & FinOps audit with the standard image in one command"。具体步骤以 https://github.com/stackql/stackql/blob/main/docs/audit.md 为准。

5. 典型适用场景

• AI agent 跨云运维:Claude / Cursor 用 StackQL MCP server 列资源、查计费、改 SG 规则,全程 SQL 表达,prompt 短、可审计。
• 跨云资产盘点 + FinOps:CI 里 stackql exec 跑只读 SQL 生成报告。
• 本地 Postgres 客户端连云:BI 工具 / 笔记本里 psql 直连 stackql srv,把云资源当表查。
• GitHub Actions 安全审计:stackql/setup-stackql-mcp@v1 + mode: read_only,PR 时自动跑基线。
• 教学 / demo:用 Jupyter(stackql-jupyter-demo 镜像,README 提及)演示 SQL 与云资源对应。

6. 坑与注意

• ⚠️ 认证是头号门槛:--auth="${AUTH}" 是所有 provider 的入口。不同 provider 凭证格式不同(AWS 是 access key,Okta 是 token,GitHub 是 PAT),AUTH 写法以 https://stackql.io/docs 为准。README 没有展开具体语法,务必先看官方 docs。
• ⚠️ Provider Registry 是另一仓库:provider 列表与版本受 stackql-provider-registry 约束;本仓库只装应用本体。
• ⚠️ SQL 方言不全是 ANSI:StackQL 把 provider API 投影成 SQL,但跨 provider JOIN、聚合、子查询的支持度不完全等同标准 PostgreSQL,跨 provider 复杂查询前先在 REPL 试。
• ⚠️ 修改类操作慎用默认凭证:MCP server 在 AI agent 下,任何 INSERT/UPDATE/DELETE 都是真实 API 调用。生产强烈建议 mode: read_only(GitHub Action 默认就是),或用最小权限的服务账号。
• ⚠️ .mcpb bundle 不是跨平台同一文件:README 列了四个独立 bundle,别下载错。
• ⚠️ audit quickstart 默认只读:"Findings, not infrastructure" 是 README 原话,别误以为是变更工具。
• ⚠️ 版本号口径:MCP 功能自 0.9.250 起;README 与博客口径一致,具体补丁级版本请查 Releases 页。

7. 与同类对比

工具	模型	切入点	学习曲线
stackql/stackql	SQL over 40+ provider + MCP server + Postgres 协议	SQL 语法;MCP 接入	中(SQL 基础 + 认证模板)
Steampipe	SQL over 云(基于 Postgres + FDW)	同上,纯 SQL	中
CloudQuery	同步云资源到 PG / DuckDB	ETL 而非查询引擎	中
aws-cli / gcloud / az	原厂 CLI	命令式 / JSON	高(每个云一套)
Pulumi / Terraform	IaC	声明式语言	高

定位:介于 Steampipe(纯 SQL 工具)与各云 CLI 之间,把"SQL 跨云"与"MCP for agent"两件事打包。Steampipe 偏分析、CloudQuery 偏数据下沉、StackQL 偏"既能查也能改,且 AI agent 直接调用"。

8. 一句话推荐结论

如果你的目标是让 AI agent 用一句 SQL 跨 40+ 云 / SaaS 操作资源,StackQL 是当前少有的"MCP server + 跨云 SQL + Postgres wire protocol"三位一体实现 — 一份 SQL 既是给 agent 看的,也是给人看的。

---

spark · 2026-09-07 · 来源:GitHub README(HTTP 200,2026-09-07 07:33 UTC 抓取)+ StackQL 官方博客 "StackQL MCP Server Now Available" + mcpservers.org 收录页 + web_search 补充。StackQL 0.9.250 是 MCP 功能首发版本(博客明示),其他细节以官方 docs 为准。