Skip to content
Back to search

stackql

Query, provision and operate Cloud, SaaS, API and Model Context Protocol (MCP) resources through a unified SQL-based framework for humans and AI agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/stackql/stackql with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/stackql/stackql'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/stackql--stackql/badge.svg)](/listings/stackql--stackql)

HTML

<a href="/listings/stackql--stackql"><img src="/api/listings/stackql--stackql/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

StackQL is available for Windows, MacOS, Linux, Docker, GitHub Actions and more. See the installation instructions below for your platform.

<details> <summary><b>Installing on MacOS</b></summary>

- Homebrew (`amd64` and `arm64`) - `brew install stackql` *or* `brew tap stackql/tap && brew install stackql/tap/stackql` - MacOS PKG Installer (`amd64` and `arm64`) - download the latest [MacOS PKG installer for StackQL][macpkg] - run the installer and follow the prompts

</details>

<details> <summary><b>Installing on Windows</b></summary>

- MSI Installer - download the latest [MSI installer for StackQL][winmsi] - run the installer and follow the prompts - Chocolatey - install [Chocolatey](https://chocolatey.org/install) - run `choco install stackql` - ZIP Archive - download the latest [Windows ZIP archive for StackQL][winzip] - extract the archive (code signed `stackql.exe` file) to a directory of your choice - add the directory to your `PATH` environment variable (optional)

</details>

<details> <summary><b>Installing on Linux</b></summary>

- ZIP Archive - download the latest [Linux ZIP archive for StackQL][tuxzip] - or via `curl -L https://bit.ly/stackql-zip -O && unzip stackql-zip` - extract the archive (`stackql` file) to a directory of your choice - add the directory to your `PATH` environment variable (optional)

</details>

<details> <summary><b>Getting StackQL from DockerHub</b></summary>

> View all available StackQL images on [__DockerHub__][dockerhub]. Images available include [__`stackql`__][dockerstackql], [__`stackql-jupyter-demo`__][dockerjupyter] and more. Pull the latest StackQL base image using:

docker pull stackql/stackql

> Want findings, not infrastructure? Run a read-only cross-cloud security & > FinOps audit with the standard image in one command — see the > [__Docker audit quickstart__](/docs/audit.md).

</details>

<details> <summary><b>Using StackQL with GitHub Actions</b></summary>

> Use StackQL in your GitHub Actions workflows to automate cloud infrastructure provisioning, IaC assurance, or compliance/security. Available GitHub Actions include: [`setup-stackql`][setupaction], [`stackql-exec`][execaction] and more

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 378 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <!-- web assets -->
  2. [logo]: https://stackql.io/img/stackql-logo-bold.png "stackql logo"
  3. [homepage]: https://stackql.io/
  4. [docs]: https://stackql.io/docs
  5. [blog]: https://stackql.io/blog
  6. [registry]: https://github.com/stackql/stackql-provider-registry
  7. [variables]: https://stackql.io/docs/getting-started/variables
  8. [macpkg]: https://storage.googleapis.com/stackql-public-releases/latest/stackql_darwin_multiarch.pkg
  9. [winmsi]: https://releases.stackql.io/stackql/latest/stackql_windows_amd64.msi
  10. [winzip]: https://releases.stackql.io/stackql/latest/stackql_windows_amd64.zip
  11. [tuxzip]: https://releases.stackql.io/stackql/latest/stackql_linux_amd64.zip
  12. <!-- docker links -->
  13. [dockerhub]: https://hub.docker.com/u/stackql
  14. [dockerstackql]: https://hub.docker.com/r/stackql/stackql
  15. [dockerjupyter]: https://hub.docker.com/r/stackql/stackql-jupyter-demo
  16. <!-- github actions links -->
  17. [setupaction]: https://github.com/marketplace/actions/stackql-studios-setup-stackql
  18. [execaction]: https://github.com/marketplace/actions/stackql-studios-stackql-exec
  19. <!-- badges -->
  20. [platforms]: https://img.shields.io/badge/platform-windows%20macos%20linux-brightgreen?style=flat-square "Platforms"
  21. [license]: https://img.shields.io/badge/license-MIT-blue?style=flat-square "License"
  22. [build]: https://github.com/stackql/stackql/actions/workflows/build.yml/badge.svg "Build"
  23. [stars]: https://img.shields.io/github/stars/stackql/stackql?style=flat-square "GitHub Stars"
  24. [forks]: https://img.shields.io/github/forks/stackql/stackql?style=flat-square "GitHub Forks"
  25. [contributors]: https://img.shields.io/github/contributors/stackql/stackql?style=flat-square "Contributors"
  26. [mcptoplistbadge]: https://mcptoplist.com/badge/io.github.stackql%2Fstackql-mcp.svg "MCP Toplist"
  27. [mcpregistrybadge]: https://img.shields.io/badge/MCP%20Registry-io.github.stackql%2Fstackql--mcp-blue?style=flat-square "MCP Registry"
  28. [mcpserver]: https://img.shields.io/npm/v/@stackql/mcp-server?style=flat-square&label=mcp%20server "MCP Server"
  29. <!-- github links -->
  30. [issues]: https://github.com/stackql/stackql/issues/new?assignees=&labels=bug&template=bug_report.md&title=%5BBUG%5D
  31. [features]: https://github.com/stackql/stackql/issues/new?assignees=&labels=enhancement&template=feature_request.md&title=%5BFEATURE%5D
  32. [developers]: /docs/developer_guide.md
  33. [registrycont]: /docs/registry_contribution.md
  34. [designdocs]: /docs/high-level-design.md
  35. [contributing]: /CONTRIBUTING.md
  36. [discussions]: https://github.com/orgs/stackql/discussions
  37. <!-- repo assets -->
  38. [darkmodeterm]: /docs/images/stackql-light-term.gif#gh-dark-mode-only
  39. [lightmodeterm]: /docs/images/stackql-dark-term.gif#gh-light-mode-only
  40. <!-- misc links -->
  41. [twitter]: https://twitter.com/stackql
  42. [mcpregistry]: https://registry.modelcontextprotocol.io/?search=stackql
  43. [mcptoplist]: https://mcptoplist.com/server/io.github.stackql%2Fstackql-mcp
  44. [npmjsmcpregistry]: https://www.npmjs.com/package/@stackql/mcp-server
  45. [mcpdocs]: https://stackql.io/docs
  46. <!-- language: lang-none -->
  47. <div align="center">
  48. [![logo]][homepage]
  49. ![platforms]
  50. ![license]
  51. ![build]
  52. [![MCP Toplist][mcptoplistbadge]][mcptoplist]
  53. [![MCP Registry][mcpregistrybadge]][mcpregistry]
  54. [![MCP Server][mcpserver]][npmjsmcpregistry]
  55. ![GitHub Release](https://img.shields.io/github/v/release/stackql/stackql?label=github%20release)
  56. ![GitHub Downloads](https://img.shields.io/github/downloads/stackql/stackql/total?label=github%20downloads)
  57. ![Docker Pulls](https://img.shields.io/docker/pulls/stackql/stackql)
  58. ![stars]
  59. </div>
  60. <!-- <div align="center"> -->
  61. <!-- ![GitHub Release](https://img.shields.io/github/v/release/stackql/stackql?label=github%20release) -->
  62. <!-- ![GitHub Downloads](https://img.shields.io/github/downloads/stackql/stackql/total?label=github%20downloads) -->
  63. <!-- ![Docker Pulls](https://img.shields.io/docker/pulls/stackql/stackql) -->
  64. <!-- ![Chocolatey Downloads](https://img.shields.io/chocolatey/dt/stackql?label=chocolatey%20downloads) -->
  65. <!-- ![Docker Image Version](https://img.shields.io/docker/v/stackql/stackql?label=docker%20version) -->
  66. <!-- ![Chocolatey Version](https://img.shields.io/chocolatey/v/stackql) -->
  67. <!-- ![homebrew version](https://img.shields.io/homebrew/v/stackql?label=homebrew%20version) -->
  68. <!-- ![homebrew downloads](https://img.shields.io/homebrew/installs/dy/stackql?label=homebrew%20downloads) -->
  69. <!-- ![PyPI - Downloads](https://img.shields.io/pypi/dm/stackql-deploy?label=pypi%20downloads) -->
  70. <!-- </div> -->
  71. <div align="center">
  72. ### Deploy, manage and query cloud resources and interact with APIs using SQL
  73. _The Universal Interface for the Agentic Era. Configuration-as-Data. Infrastructure-as-Context._
  74. <!-- <h3 align="center">SQL based XOps, observability and middleware framework</h3> -->
  75. <p align="center">
  76. [__Read the docs »__][docs]
  77. [Raise an Issue][issues] ·
  78. [Request a Feature][features] ·
  79. [Developer Guide][developers] ·
  80. [BYO Providers][registrycont]
  81. </p>
  82. </div>
  83. <details open="open">
  84. <summary>Contents</summary>
  85. <ol>
  86. <li><a href="#about-the-project">About The Project</a></li>
  87. <li><a href="#mcp-server">MCP Server</a></li>
  88. <li><a href="#installation">Installation</a></li>
  89. <li><a href="#usage">Usage</a></li>
  90. <!-- <li><a href="#roadmap">Roadmap</a></li> -->
  91. <li><a href="#contributing">Contributing</a></li>
  92. <li><a href="#license">License</a></li>
  93. <li><a href="#contact">Contact</a></li>
  94. <li><a href="#acknowledgements">Acknowledgements</a></li>
  95. </ol>
  96. </details>
  97. ## About The Project
  98. [__StackQL__][homepage] 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.).
  99. <br />
  100. <br />
  101. ![stackql-shell][darkmodeterm]
  102. ![stackql-shell][lightmodeterm]
  103. ### How it works
  104. StackQL is a standalone application that can be used in client mode (via __`exec`__ or __`shell`__) or accessed via a Postgres wire protocol client (`psycopg2`, etc.) using server mode (__`srv`__).
  105. StackQL parses SQL statements and transpiles them into API requests to the (cloud) resource provider. The API calls are then executed and the results are returned to the user.
  106. StackQL provider interfaces are canonically defined in OpenAPI extensions to the providers' specification. These definitions are then used to generate the SQL schema and the API client. The source for the provider definitions are stored in the [__StackQL Registry__][registry]. The semantics of provider interactions are defined in [our `any-sdk` library](https://github.com/stackql/any-sdk). For more detail on nuts and bolts, please see [the local `AGENTS.md` file](/AGENTS.md) and [that of `any-sdk`](https://github.com/stackql/any-sdk/blob/main/AGENTS.md).
  107. <details>
  108. <summary><b>StackQL Context Diagram</b></summary>
  109. <br />
  110. The following context diagram describes the StackQL architecture at a high level:
  111. <!-- ![StackQL Context Diagram](http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/stackql/test-readme/main/puml/stackql-c4-context.iuml) -->
  112. ```mermaid
  113. flowchart LR
  114. subgraph StackQL
  115. direction BT
  116. subgraph ProviderDefs
  117. Registry[Provider Registry Docs]
  118. end
  119. subgraph App
  120. Proc[$ stackql exec\n$ stackql shell\n$ stackql srv]
  121. style Proc fill:#000,stroke:#000,color:#fff,text-align:left;
  122. %% ,font-family:'Courier New', Courier, monospace
  123. end
  124. end
  125. User((User)) <--> StackQL <--> Provider[Cloud Provider API]
  126. ProviderDefs --> App
  127. ```
  128. More detailed design documentation can be found in the [here][designdocs].
  129. </details>
  130. ## MCP Server
  131. StackQL is an [MCP](https://modelcontextprotocol.io) server - SQL over 40+ cloud and SaaS providers for AI agents. Point any MCP-capable client (Claude, VS Code, Cursor, etc.) at StackQL and it can query and provision cloud resources using SQL.
  132. Run it over stdio:
  133. ```sh
  134. stackql mcp --mcp.server.type=stdio
  135. ```
  136. StackQL MCP is published to the [Official MCP Registry][mcpregistry] as `io.github.stackql/stackql-mcp` and distributed via npm, PyPI, Docker, a GitHub Action and `.mcpb` bundles. Pick an install vector and add the matching block to your MCP client config:
  137. <details>
  138. <summary><b>npm (npx)</b></summary>
  139. ```json
  140. {
  141. "mcpServers": {
  142. "stackql": {
  143. "command": "npx",
  144. "args": ["-y", "@stackql/mcp-server"]
  145. }
  146. }
  147. }
  148. ```
  149. </details>
  150. <details>
  151. <summary><b>PyPI (uvx)</b></summary>
  152. ```json
  153. {
  154. "mcpServers": {
  155. "stackql": {
  156. "command": "uvx",
  157. "args": ["stackql-mcp-server"]
  158. }
  159. }
  160. }
  161. ```
  162. </details>
  163. <details>
  164. <summary><b>Docker</b></summary>
  165. ```json
  166. {
  167. "mcpServers": {
  168. "stackql": {
  169. "command": "docker",
  170. "args": ["run", "-i", "--rm", "stackql/stackql-mcp"]
  171. }
  172. }
  173. }
  174. ```
  175. </details>
  176. <details>
  177. <summary><b>.mcpb bundle</b></summary>
  178. > Download the bundle for your platform from the [latest release](https://github.com/stackql/stackql/releases/latest) and install it in your MCP client (one-click in clients that support `.mcpb`).
  179. - `stackql-mcp-linux-x64.mcpb`
  180. - `stackql-mcp-linux-arm64.mcpb`
  181. - `stackql-mcp-windows-x64.mcpb`
  182. - `stackql-mcp-darwin-universal.mcpb`
  183. </details>
  184. <details>
  185. <summary><b>GitHub Actions</b></summary>
  186. > Wire StackQL MCP into agentic CI workflows. Defaults to `read_only` mode, the safe default for CI.
  187. ```yaml
  188. - uses: stackql/setup-stackql-mcp@v1
  189. with:
  190. mode: read_only
  191. ```
  192. </details>
  193. For client-specific setup, authentication and server modes, see the [full MCP install and usage docs][mcpdocs].
  194. ## Installation
  195. StackQL is available for Windows, MacOS, Linux, Docker, GitHub Actions and more. See the installation instructions below for your platform.
  196. <details>
  197. <summary><b>Installing on MacOS</b></summary>
  198. - Homebrew (`amd64` and `arm64`)
  199. - `brew install stackql` *or* `brew tap stackql/tap && brew install stackql/tap/stackql`
  200. - MacOS PKG Installer (`amd64` and `arm64`)
  201. - download the latest [MacOS PKG installer for StackQL][macpkg]
  202. - run the installer and follow the prompts
  203. </details>
  204. <details>
  205. <summary><b>Installing on Windows</b></summary>
  206. - MSI Installer
  207. - download the latest [MSI installer for StackQL][winmsi]
  208. - run the installer and follow the prompts
  209. - Chocolatey
  210. - install [Chocolatey](https://chocolatey.org/install)
  211. - run `choco install stackql`
  212. - ZIP Archive
  213. - download the latest [Windows ZIP archive for StackQL][winzip]
  214. - extract the archive (code signed `stackql.exe` file) to a directory of your choice
  215. - add the directory to your `PATH` environment variable (optional)
  216. </details>
  217. <details>
  218. <summary><b>Installing on Linux</b></summary>
  219. - ZIP Archive
  220. - download the latest [Linux ZIP archive for StackQL][tuxzip]
  221. - or via `curl -L https://bit.ly/stackql-zip -O && unzip stackql-zip`
  222. - extract the archive (`stackql` file) to a directory of your choice
  223. - add the directory to your `PATH` environment variable (optional)
  224. </details>
  225. <details>
  226. <summary><b>Getting StackQL from DockerHub</b></summary>
  227. > View all available StackQL images on [__DockerHub__][dockerhub]. Images available include [__`stackql`__][dockerstackql], [__`stackql-jupyter-demo`__][dockerjupyter] and more. Pull the latest StackQL base image using:
  228. ```bash
  229. docker pull stackql/stackql
  230. ```
  231. > Want findings, not infrastructure? Run a read-only cross-cloud security &
  232. > FinOps audit with the standard image in one command — see the
  233. > [__Docker audit quickstart__](/docs/audit.md).
  234. </details>
  235. <details>
  236. <summary><b>Using StackQL with GitHub Actions</b></summary>
  237. > Use StackQL in your GitHub Actions workflows to automate cloud infrastructure provisioning, IaC assurance, or compliance/security. Available GitHub Actions include: [`setup-stackql`][setupaction], [`stackql-exec`][execaction] and more
  238. </details>
  239. ## Usage
  240. Caller authentication and permissions: [configuration](docs/access_management.md) and
  241. [four tested walkthroughs](docs/examples/access-management/README.md).
  242. StackQL can be used via the interactive REPL shell, or via the `exec` command or ran as a server using the [Postgres wire protocol](https://www.postgresql.org/docs/current/protocol.html).
  243. For provider authentication, StackQL uses the provider's default configuration when no `--auth` override is supplied. Set the environment variables required by the provider before running queries. For example, AWS uses `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`. See [provider authentication examples](docs/auth.md).
  244. > ℹ️ StackQL does not require or install a database.
  245. * Interactive Shell
  246. ```sh
  247. # run interactive stackql queries
  248. stackql shell
  249. ```
  250. * Execute a statement or file
  251. ```sh
  252. stackql exec -i myscript.iql --iqldata vars.jsonnet --output json
  253. # or
  254. stackql exec "SELECT id, status FROM aws.ec2.instances WHERE region = 'us-east-1'"
  255. ```
  256. > ℹ️ output options of `json`, `csv`, `table` and `text` are available for the `exec` command using the `--output` flag
  257. > ℹ️ StackQL supports passing parameters using `jsonnet` or `json`, see [__Using Variables__][variables]
  258. * Server
  259. ```sh
  260. # serve client requests over the Postgres wire protocol (psycopg2, etc.)
  261. # clients are not authenticated unless mTLS is configured via --pgsrv.tls, so keep the listener on loopback otherwise
  262. stackql srv --pgsrv.address=127.0.0.1
  263. ```
  264. To override a provider's default authentication, supply an auth JSON object with `--auth`, for example `stackql shell --auth="${AUTH}"`.
  265. _For more examples, please check our [Blog][blog]_
  266. <!-- ## Roadmap
  267. See our [__roadmap__](https://github.com/othneildrew/Best-README-Template/issues) to see where we are going with the project. -->
  268. ## Contributing
  269. Contributions are welcome and encouraged. For more information on how to contribute, please see our [__contributing guide__][contributing].
  270. ## License
  271. Distributed under the MIT License. See [`LICENSE`](https://github.com/stackql/stackql/blob/main/LICENSE) for more information. Licenses for third party software we are using are included in the [/docs/licenses](/docs/licenses) directory.
  272. ## Contact
  273. Get in touch with us via Twitter at [__@stackql__][twitter], email us at [__info@stackql.io__](info@stackql.io) or start a conversation using [__discussions__][discussions].
  274. ## Acknowledgements
  275. Forks of the following support our work:
  276. * [vitess](https://vitess.io/)
  277. * [kin-openapi](https://github.com/getkin/kin-openapi)
  278. * [gorilla/mux](https://github.com/gorilla/mux)
  279. * [readline](https://github.com/chzyer/readline)
  280. * [psql-wire](https://github.com/jeroenrinzema/psql-wire)
  281. * [mcp-postgres](https://github.com/gldc/mcp-postgres)
  282. * [the `golang` MCP SDK](https://github.com/modelcontextprotocol/go-sdk)
  283. * ...and more. Please excuse us for any omissions.
  284. We gratefully acknowledge these pieces of work.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.