Skip to main content

Installation

Instructions for installing StackQL on various different platforms are provided here.

macOS​

StackQL is available on macOS via Homebrew and the pkg Installer, both ARM (M1/Apple Silicon) and AMD architectures are supported with a single multi-arch installer.

Homebrew

To install via Homebrew, run the following command in your terminal:

brew install stackql

Package download

StackQL is available as a signed and notarized, interactive pkg installer for MacOS.

Download macOS PKG  

Installing the MCP server​

The StackQL MCP server lets AI agents query and provision cloud resources using StackQL. It ships through several channels - they all run the same server, so pick the channel that matches your client and your trust requirements. The options below are listed roughly in order of trust and ease.

Marketplaces and directories​

The server is published to the Official MCP Registry as io.github.stackql/stackql-mcp; the package registries below carry the distributable artifacts, and downstream directories pick the listing up from there.

RegistryTypePublished viaListingNotes
Official MCP RegistryCanonical metadata registrymcp-publisher CLI + server.jsonmodelcontextprotocol.io/search
modelcontextprotocol.io/direct		advertises all 7 package types (mcpb x4, oci, npm, pypi)
npmPackage registrynpm publish@stackql/mcp-servernpx launcher
PyPIPackage registrytwine uploadstackql-mcp-serveruvx / pip launcher
Docker HubContainer registrydocker buildx --pushstackql/stackql-mcpmulti-arch amd64 + arm64
GitHub Actions MarketplaceCI marketplace (setup-stackql-mcp action)Public repo + release + marketplace listingsetup-stackql-mcp-serverVerified publisher; stackql/setup-stackql-mcp

Prebuilt .mcpb bundle​

When to use: Claude Desktop, no separate StackQL install, and you want a signed one-click bundle.

A prebuilt MCP Bundle is attached to every StackQL release for each platform:

https://github.com/stackql/stackql/releases/latest/download/stackql-mcp-<platform>.mcpb

where <platform> is one of darwin-universal, windows-x64, linux-x64, or linux-arm64. Download buttons for each platform are in the Claude Desktop / MCP tab above. Each bundle has a matching .sha256 checksum on the release page. Verify it, then install via Settings -> Extensions in Claude Desktop:

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

See Using StackQL with Claude Desktop for the full walkthrough.

Manual claude_desktop_config.json​

When to use: you already have the stackql binary on your PATH and use Claude Desktop or any other stdio MCP client.

{
  "mcpServers": {
    "stackql": {
      "command": "stackql",
      "args": [
        "mcp",
        "--mcp.server.type=stdio",
        "--approot", "/Users/you/.stackql",
        "--mcp.config", "{\"server\": {\"audit\": {\"disabled\": true}}}"
      ]
    }
  }
}

All three arguments are load-bearing:

  • --mcp.server.type=stdio selects the stdio transport that editor-embedded clients speak.
  • --approot points the provider cache at a writable directory. MCP clients may launch the server with the working directory set to /, which is not writable.
  • --mcp.config '{"server": {"audit": {"disabled": true}}}' disables the audit log, which otherwise defaults its directory to the (possibly non-writable) working directory.

Add provider credentials with an "env" block and tune the safety contract with "mode" - see Server modes.

npx (no install)​

When to use: any Node environment, when you do not want a global StackQL install.

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

The @stackql/mcp-server launcher downloads the signed stackql binary on first run, verifies its SHA-256, and caches it for subsequent runs.

uvx / pip (Python)​

When to use: a Python environment - the same launcher packaged for Python, sharing the binary cache the npx launcher populates.

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

Or install it into the current environment with pip install stackql-mcp-server (Python 3.9+). The package is stackql-mcp-server on PyPI.

Docker​

When to use: a containerised or otherwise isolated runtime. The image is multi-arch (amd64 and arm64).

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

As a client configuration:

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

The image is stackql/stackql-mcp on Docker Hub.

CI and agentic workflows (GitHub Actions)​

When to use: run the server inside a GitHub Actions job so an agent can query - and, if you allow it, act on - your cloud as part of CI.

stackql/setup-stackql-mcp@v1 installs the binary and writes an MCP config (defaulting to read_only mode). Pass that config to anthropics/claude-code-action through claude_args:

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

See the action README for more agentic recipes (cloud audits, cost estimates, and so on).

Embedded MCP​

When to use: you are building an agentic app and want to vendor the MCP server into your own binary - no npx, no separate install, no runtime dependency.

Native libraries spawn the signed stackql binary over stdio behind each language's official MCP SDK client, so your app gets the same governed SQL interface to every provider in the registry. Each library defaults to read_only - escalation to a writable mode is always explicit - and can either download-and-verify the binary on first run or vendor it into your build for a single self-contained executable. The full per-language API is in the Embedded MCP reference.

The stackql-mcp crate spawns the binary behind an rmcp client. The default sidecar feature downloads and verifies the binary on first run; the vendored feature embeds it with include_bytes! for a single self-contained binary. 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?;
View on GitHub  
View on crates.io  

Full reference: Embedded MCP: Rust.

Trust model​

The same security properties hold across every channel:

  • The embedded stackql binary is Authenticode-signed (Windows) and Apple-notarised (macOS).
  • Every .mcpb bundle ships with a published SHA-256 checksum on the release page.
  • The npx and uvx launchers verify the downloaded binary's SHA-256 before first use.
  • The MCP Registry entry attests the per-platform hashes.

Using GitHub Actions​

StackQL GitHub Actions are available for use in your GitHub Actions workflows. The following actions are available:

stackql-deploy​

Deploy or test infrastructure stacks using StackQL directly from your GitHub workflows. This action enables Infrastructure as Code (IaC) workflows using SQL-like syntax, allowing you to define, deploy, and manage cloud resources across multiple providers in a single workflow.

View on the GitHub Marketplace  

Example usage

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

Other Libraries​

StackQL provides several integration methods that allow you for use in different programming languages and environments. These libraries extend StackQL's functionality, making it easy to incorporate cloud resource querying and management into your existing applications and workflows.

pystackql Python Package​

Python wrapper to use StackQL in your Python programs. The pystackql package is available on PyPi, documentation for the pystackql package is available via Read the Docs. To install the pystackql package, run the following command:

pip install pystackql

The following example shows the pystackql package used along with pandas to run StackQL queries and return the results to a 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)