# Instalação

> Instale o StackQL no macOS, Linux, Windows, Docker ou em um shell na nuvem e use o servidor MCP do StackQL no Claude Desktop, ChatGPT, Goose e outros clientes MCP, ou via npx, uvx, pip, Docker e GitHub Actions.

Source: https://stackql.io/pt-br/installing-stackql

Esta página contém as instruções para instalar o StackQL em diversas plataformas.

**macOS**

## macOS

O StackQL está disponível no macOS via Homebrew e pelo instalador `pkg`; um único instalador multiarquitetura oferece suporte tanto à arquitetura ARM (M1/Apple Silicon) quanto à AMD.

**Homebrew**

Para instalar via Homebrew, execute o comando a seguir no seu terminal:

```bash
brew install stackql
```

**curl (binário assinado e notarizado)**

Para instalar um binário executável `stackql` assinado e notarizado no diretório atual, execute o comando a seguir no seu terminal:

```bash
curl -fsSL https://get-stackql.io/install | sh
```

**Download do pacote**

O StackQL está disponível como um instalador `pkg` interativo, assinado e notarizado, para macOS.

[Baixar PKG para macOS](https://releases.stackql.io/stackql/latest/stackql_darwin_multiarch.pkg)

**Linux**

## Linux

O StackQL está disponível para todas as arquiteturas Linux.

**curl**

Para instalar um binário executável `stackql` no diretório atual para a sua arquitetura Linux (amd64 ou arm64), execute o comando a seguir no seu terminal:

```bash
curl -fsSL https://get-stackql.io/install | sh
```

**Download do pacote**

Como alternativa, você pode baixar os binários aqui:

[Baixar ZIP para Linux (amd64)](https://releases.stackql.io/stackql/latest/stackql_linux_amd64.zip)
[Baixar ZIP para Linux (arm64)](https://releases.stackql.io/stackql/latest/stackql_linux_arm64.zip)

**Windows**

## Windows

O StackQL está disponível no Windows via Chocolatey, pelo script de instalação do PowerShell e pelo instalador MSI. Builds nativos AMD64 (x64) e ARM64 estão disponíveis como instaladores MSI e arquivos ZIP que contêm `stackql.exe`. O build AMD64 também funciona em ARM64 por emulação. Todos os executáveis são assinados com um certificado de assinatura de código Authenticode.

**Chocolatey**

Para instalar via Chocolatey, execute o comando a seguir no seu terminal PowerShell ou `cmd`:

```powershell
choco install stackql
```

**Invoke-RestMethod**

Para instalar um executável Authenticode no diretório atual, execute o seguinte em um terminal PowerShell: 

```powershell
Invoke-RestMethod https://get-stackql.io/install | Invoke-Expression
# or
irm https://get-stackql.io/install | iex
```

**Download de MSI/ZIP**

Baixe abaixo o instalador ou o executável `stackql` assinado para Windows. Clicar em um botão de download seleciona AMD64 por padrão; use o menu suspenso do botão para escolher AMD64 ou ARM64 nativo.

[Baixar MSI para Windows](https://releases.stackql.io/stackql/latest/stackql_windows_amd64.msi)
[Baixar ZIP para Windows](https://releases.stackql.io/stackql/latest/stackql_windows_amd64.zip)

**Docker**

## Docker

Os builds do StackQL são publicados no [DockerHub](https://hub.docker.com/u/stackql).  

__Docker Hub__  

Para baixar a imagem de contêiner do StackQL, execute o comando a seguir:

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

A partir da `v1.0`, a imagem é baseada no Ubuntu 26.04 LTS, e uma variante com o Python 3.13 pré-instalado é publicada com o sufixo de tag `-python3.13` (alias `-python3`), por exemplo:

```bash
docker pull stackql/stackql:latest-python3.13
```

**stackql-deploy**

## `stackql-deploy`

O `stackql-deploy` é um framework de IaC sem estado construído sobre o StackQL. Para ver a documentação completa, consulte a [__documentação do StackQL Deploy__](https://stackql-deploy.io/).

__Linux / macOS__

Baixa e extrai o binário mais recente do `stackql-deploy` em uma única etapa. O instalador detecta o seu sistema operacional e a sua arquitetura (incluindo Apple Silicon e Intel, por meio de um binário universal para macOS) e obtém automaticamente o artefato correto da versão.
```bash
curl -fsSL https://get-stackql-deploy.io/install.sh | sh
```

__Windows__

Baixa e extrai o binário mais recente do `stackql-deploy` no diretório atual.
O instalador detecta a sua plataforma e obtém automaticamente o artefato correto da versão.
```powershell
irm https://get-stackql-deploy.io/install.ps1 | iex
```

__cargo__

Se você tiver o toolchain do Rust instalado, este comando compila e instala o binário diretamente do [__crates.io__](https://crates.io/crates/stackql-deploy).
```bash
cargo install stackql-deploy
```

**Shells na nuvem**

## Shells na nuvem

Você pode usar o StackQL diretamente nos shells na nuvem e terminais web integrados das principais plataformas de nuvem e de dados. Isso oferece uma experiência sem atritos, pois esses ambientes já estão pré-autorizados com a identidade com a qual você fez login, o que dispensa uma configuração de autenticação separada.

**AWS**

### AWS CloudShell

O AWS CloudShell oferece um shell no navegador com a AWS CLI pré-instalada e autenticada. Executar o StackQL no AWS CloudShell permite consultar e gerenciar recursos da AWS sem etapas adicionais de autenticação. Para obter instruções detalhadas, consulte nosso [tutorial do AWS CloudShell](/quick-starts/aws/aws-cloud-shell).

Primeiro, baixe o pacote do StackQL:

```bash
curl -fsSL https://get-stackql.io/install/aws | sh
```
Em seguida, execute o script do StackQL para o AWS CloudShell:

```bash
./stackql-aws-cloud-shell.sh
```  

Esse script inicia um shell de comandos do StackQL com as suas credenciais do AWS CloudShell, para que você comece a consultar recursos da AWS imediatamente.

**Azure**

### Azure Cloud Shell

O Azure Cloud Shell oferece um ambiente de shell acessível pelo navegador com a Azure CLI pré-autenticada na sua conta do Azure. Usar o StackQL no Azure Cloud Shell permite consultar os seus recursos do Azure sem atritos e sem configuração adicional. Para obter todos os detalhes, consulte nosso [guia do Azure Cloud Shell](/blog/tutorials/using-stackql-in-native-cloud-shells-in-aws-azure-and-gcp#using-stackql-in-the-azure-cloud-shell).  

Primeiro, baixe o pacote do StackQL:

```bash
curl -fsSL https://get-stackql.io/install/azure | sh
```

Em seguida, execute o script do StackQL para o Azure Cloud Shell:

```bash
./stackql-azure-cloud-shell.sh
```

Esse script configura automaticamente uma sessão do StackQL para usar as suas credenciais do Azure Cloud Shell, o que permite consultar imediatamente os seus recursos do Azure.

**Google**

### Google Cloud Shell

O Google Cloud Shell oferece um ambiente de desenvolvimento e operações com a Google Cloud CLI já autenticada. Executar o StackQL no Google Cloud Shell permite consultar recursos do GCP com a sua autenticação existente. Saiba mais no nosso [guia do Google Cloud Shell](/blog/tutorials/using-stackql-in-native-cloud-shells-in-aws-azure-and-gcp#using-stackql-in-the-google-cloud-shell).  

Primeiro, baixe o pacote do StackQL:

```bash
curl -fsSL https://get-stackql.io/install/google | sh
```

Em seguida, execute o script do StackQL para o Google Cloud Shell:

```bash
./stackql-google-cloud-shell.sh
```

O script configura o StackQL para usar as suas credenciais do Google Cloud Shell, para que você comece imediatamente a consultar os seus recursos do GCP com sintaxe SQL.

**Databricks**

### Databricks Web Terminal

Os espaços de trabalho do Databricks incluem um terminal web que é executado como o usuário conectado. Executar o StackQL nele permite consultar o seu espaço de trabalho com a sua identidade do Databricks, sem uma configuração de autenticação separada. Para ver exemplos de consultas e a autenticação no nível da conta, consulte nosso [guia do Databricks Web Terminal](/blog/tutorials/stackql-in-databricks-web-terminal).

Primeiro, baixe o pacote do StackQL:

```bash
curl -fsSL https://get-stackql.io/install/databricks | sh
```

Em seguida, execute o script de shell do StackQL para o Databricks:

```bash
./stackql-databricks-shell.sh
```

Isso inicia uma sessão do StackQL com a identidade do seu espaço de trabalho do Databricks, para que você possa consultar imediatamente recursos no escopo do espaço de trabalho, como `databricks_workspace.iam.vw_user_entitlements`. Para consultas no nível da conta (provisionamento, faturamento, IAM da conta), defina as variáveis do principal de serviço OAuth2 do Databricks conforme descrito no guia.

## Usar com clientes MCP

O servidor MCP do StackQL é executado localmente via stdio, então as credenciais dos providers ficam na sua máquina, seja qual for o cliente que você usar. Escolha o seu cliente abaixo: cada aba mostra primeiro a opção pelo diretório ou com um clique e, como alternativa, a configuração manual. Para ver todos os canais de distribuição, incluindo `npx`, Python, Docker e CI, consulte [Instalar o servidor MCP](#installing-the-mcp-server).

**Claude Desktop**

### Claude Desktop

  A forma recomendada de instalar o servidor MCP do StackQL no Claude Desktop é pelo [Anthropic Connector Directory](https://claude.ai/directory/connectors/ant.dir.gh.stackql.stackql) (**Settings -> Connectors -> Add -> Browse Connectors**, pesquise **StackQL**) - o Claude Desktop seleciona automaticamente o binário assinado correto para a sua plataforma.  Como alternativa, cada versão do StackQL traz MCP Bundles (`.mcpb`) pré-compilados anexados, para instalação a partir de um arquivo baixado - em nenhum dos casos é necessária uma instalação separada do StackQL.  Os bundles estão disponíveis para macOS, Windows e Linux.

  Os downloads de MCPB para Linux e Windows usam **amd64** (x64) por padrão. Use os menus suspensos para selecionar **amd64** ou **arm64**.

  [Baixar MCPB para macOS](https://releases.stackql.io/stackql/latest/stackql-mcp-darwin-universal.mcpb)
[Baixar MCPB para Linux](https://releases.stackql.io/stackql/latest/stackql-mcp-linux-x64.mcpb)
[Baixar MCPB para Windows](https://releases.stackql.io/stackql/latest/stackql-mcp-windows-x64.mcpb)

:::info

O servidor MCP do StackQL também está listado no [__Official MCP Registry__](https://registry.modelcontextprotocol.io/v0/servers?search=stackql) como `io.github.stackql/stackql-mcp`.

:::

:::tip

O bundle é uma das várias formas de executar o servidor MCP do StackQL.  Consulte [__Usar o StackQL com o Claude Desktop__](/getting-started/claude-desktop) para ver o passo a passo completo do Claude Desktop, ou [__Instalar o servidor MCP__](#installing-the-mcp-server) para as opções npx, Docker, Python, CI e manual.

:::

**ChatGPT**

### ChatGPT e Codex

  O StackQL é distribuído como um plugin local para o aplicativo de desktop do ChatGPT e a CLI do Codex. O plugin executa o servidor MCP do StackQL via stdio na sua máquina, então as credenciais dos providers nunca saem dela. É necessário o Node.js 24.22.1 ou posterior (22.23.4 ou 26.12.1 nessas linhas de versão); o plugin precisa apenas dos módulos integrados do Node.js, baixa o binário `stackql` assinado no primeiro uso e verifica o SHA-256 dele.

  **Aplicativo de desktop do ChatGPT (diretório de plugins):**  

  abra o diretório de plugins no aplicativo de desktop do ChatGPT, pesquise **StackQL**, clique em **Install** e depois execute a configuração do plugin; a skill `stackql-setup` incluída orienta você na configuração das credenciais e em uma primeira consulta. A listagem exibe o selo **Desktop only**: o plugin só é instalado pelo aplicativo de desktop, não pelo ChatGPT na web ou no celular, e as ferramentas dele ficam disponíveis no modo Work, em threads executadas no seu computador. Se a listagem ainda não aparecer no seu diretório, instale pelo marketplace do repositório.

  **Aplicativo de desktop do ChatGPT (marketplace do repositório):**  

  abra **Settings -> Plugins -> Add -> Add from GitHub**, digite `stackql/stackql`, depois instale o **StackQL** pela seção **Personal** do diretório de plugins e reinicie o aplicativo.

  **CLI do Codex:**

  ```shell
  codex plugin marketplace add stackql/stackql --sparse .agents/plugins --sparse packaging/openai-plugin
  codex plugin add stackql@stackql
  ```

  Reinicie o aplicativo de desktop do ChatGPT ou o Codex e depois experimente: *Use o StackQL para instalar o provider do GitHub, se necessário, e depois liste os cinco primeiros serviços do GitHub.* As credenciais dos providers ficam em `~/.stackql/.env`, com os nomes padrão de variáveis de ambiente de cada provider (por exemplo, `AWS_ACCESS_KEY_ID` e `AWS_SECRET_ACCESS_KEY`); depois de editar o arquivo, peça ao agente para chamar `reload_credentials`.

  **Sem o plugin:**   

  em **Settings -> Plugins -> MCPs -> Connect to a custom MCP**, escolha **STDIO**, defina o comando como `npx` e adicione os argumentos `-y` e `@stackql/mcp-server`. Informe as credenciais dos providers como variáveis de ambiente nesse formulário.

:::note

O ChatGPT na web e no celular não consegue executar um servidor stdio local, por isso o plugin funciona apenas no desktop e no Codex. Um bug em aberto do aplicativo de desktop do ChatGPT ([openai/codex#38162](https://github.com/openai/codex/issues/38162)) pode ocultar as ferramentas MCP locais nas sessões de **Chat**; as threads do modo Work, as threads do Codex e a CLI do Codex não são afetadas.

:::

**Goose**

### Goose

  O Goose executa extensões stdio diretamente, então o inicializador `npx` é tudo de que você precisa (Node.js 18 ou posterior).

  **Goose Desktop:** clique no botão abaixo. O Goose abre, mostra o comando que vai executar e pede a sua confirmação; depois, adiciona o StackQL como extensão.

  Instalar no Goose Desktop

  O botão é um deep link `goose://`; você também pode colá-lo na barra de endereços do navegador ou abri-lo em um terminal com `open` (macOS), `start` (Windows) ou `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
  ```

  **CLI do Goose:**

  ```shell
  goose session --with-extension "npx -y @stackql/mcp-server"
  ```

  ou execute `goose configure`, escolha **Add Extension -> Command-line Extension** e digite o mesmo comando. Informe as credenciais dos providers como variáveis de ambiente da extensão quando solicitado.

:::note

O Goose desativou o diretório de extensões dentro do aplicativo em favor do [Official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=stackql), onde o StackQL está listado como `io.github.stackql/stackql-mcp`. Quando o Goose disponibilizar a importação do registro, o StackQL poderá ser encontrado lá sem nenhuma ação adicional.

:::

## Instalar o servidor MCP

O servidor MCP do StackQL permite que agentes de IA consultem e provisionem recursos na nuvem com o StackQL. Ele é distribuído por vários canais - todos executam o mesmo servidor, então escolha o canal que corresponde ao seu cliente e aos seus requisitos de confiança. As opções abaixo estão listadas aproximadamente em ordem de confiança e facilidade.

### Marketplaces e diretórios

O servidor é publicado no Official MCP Registry como `io.github.stackql/stackql-mcp`; os registros de pacotes abaixo contêm os artefatos distribuíveis, e os diretórios derivados obtêm a listagem a partir dali.  

**Registros**

| Registro | Tipo | Publicado via | Listagem | Observações |
|---|---|---|---|---|
| Official MCP Registry | Registro canônico de metadados | CLI `mcp-publisher` + `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) | anuncia todos os 8 pacotes (`mcpb x5`, `oci`, `npm`, `pypi`) |
| npm | Registro de pacotes | `npm publish` | [`@stackql/mcp-server`](https://www.npmjs.com/package/@stackql/mcp-server) | inicializador `npx` |
| PyPI | Registro de pacotes | `twine upload` | [`stackql-mcp-server`](https://pypi.org/project/stackql-mcp-server/) | inicializador `uvx` / `pip` |
| Docker Hub | Registro de contêineres | `docker buildx --push` | [`stackql/stackql-mcp`](https://hub.docker.com/r/stackql/stackql-mcp) | multiarquitetura `amd64` + `arm64` |
| GitHub Actions Marketplace | Marketplace de CI (action `setup-stackql-mcp`) | Repositório público + versão + listagem no marketplace | [`setup-stackql-mcp-server`](https://github.com/marketplace/actions/setup-stackql-mcp-server) | Publicador verificado; [`stackql/setup-stackql-mcp`](https://github.com/stackql/setup-stackql-mcp) |

**Diretórios**

Listagens em diretórios e agregadores, aproximadamente em ordem de importância para a descoberta:

| Diretório | Tipo | Listagem |
|---|---|---|
| __Anthropic Connector Directory__ | Diretório dentro do aplicativo Claude Desktop | [claude.ai/directory](https://claude.ai/directory/connectors/ant.dir.gh.stackql.stackql) |
| __OpenAI Plugin Directory__ | Diretório dentro do aplicativo de desktop do ChatGPT (somente desktop) | pesquise **StackQL** no aplicativo de desktop do ChatGPT; consulte [ChatGPT e Codex](#using-with-mcp-clients) |
| __Cursor Directory__ | Diretório de um cliente IDE | [cursor.directory](https://cursor.directory/plugins/stackql-mcp-server) |
| __mcp.so__ | Maior agregador | [mcp.so](https://mcp.so/server/stackql/stackql) |
| __PulseMCP__ | Descoberta, apoiador do registro | [pulsemcp](https://www.pulsemcp.com/servers/stackql) |
| __Glama.ai MCP__ | Marketplace pesquisável | [glama.ai](https://glama.ai/mcp/servers/stackql/stackql) |
| __mcpmarket.com__ | Agregador | [mcpmarket](https://mcpmarket.com/server/stackql) |
| __mcpservers.org__ | Site no estilo awesome-list | [mcpservers.org](https://mcpservers.org/servers/stackql-mcp-server) |

### Bundle `.mcpb` pré-compilado

**Quando usar:** Claude Desktop sem acesso ao Connector Directory, ou quando você quer fixar uma versão específica ou verificar as somas de verificação por conta própria antes de instalar.  Para a maioria dos usuários do Claude Desktop, o [Anthropic Connector Directory](https://claude.ai/directory/connectors/ant.dir.gh.stackql.stackql) é o método de instalação recomendado.

Cada versão do StackQL traz anexado um MCP Bundle pré-compilado para cada plataforma:

```
https://releases.stackql.io/stackql/latest/stackql-mcp-<platform>.mcpb
```

em que `<platform>` é um destes valores: `darwin-universal`, `windows-x64` (AMD64), `windows-arm64`, `linux-x64` ou `linux-arm64`. Os botões de download de cada plataforma estão na aba **Claude Desktop**, em [Usar com clientes MCP](#using-with-mcp-clients). Cada bundle tem uma soma de verificação `.sha256` correspondente na [página da versão](https://github.com/stackql/stackql/releases/latest). Verifique-a e depois instale via **Settings -> Extensions** no Claude Desktop:

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

Consulte [Usar o StackQL com o Claude Desktop](/getting-started/claude-desktop#install-from-a-downloaded-bundle) para ver o passo a passo completo.

### `claude_desktop_config.json` manual

**Quando usar:** você já tem o binário `stackql` no PATH e usa o Claude Desktop ou qualquer outro cliente MCP stdio.

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

Os três argumentos são indispensáveis:

- `--mcp.server.type=stdio` seleciona o transporte stdio usado pelos clientes incorporados em editores.
- `--approot` aponta o cache de providers para um diretório com permissão de gravação. Os clientes MCP podem iniciar o servidor com o diretório de trabalho definido como `/`, que não tem permissão de gravação.
- `--mcp.config '{"server": {"audit": {"disabled": true}}}'` desabilita o log de auditoria, que, caso contrário, usa como diretório padrão o diretório de trabalho (possivelmente sem permissão de gravação).

Adicione as credenciais dos providers com um bloco `"env"` e ajuste o contrato de segurança com `"mode"` - consulte [Modos do servidor](/command-line-usage/mcp#server-modes).

### `npx` (sem instalação)

**Quando usar:** qualquer ambiente Node, quando você não quer uma instalação global do StackQL.

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

O inicializador [`@stackql/mcp-server`](https://www.npmjs.com/package/@stackql/mcp-server) baixa o binário `stackql` assinado na primeira execução, verifica o SHA-256 dele e o armazena em cache para as execuções seguintes.

### `uvx` / `pip` (Python)

**Quando usar:** um ambiente Python - o mesmo inicializador, empacotado para Python, que compartilha o cache de binários preenchido pelo inicializador npx.

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

Ou instale-o no ambiente atual com `pip install stackql-mcp-server` (Python 3.9+). O pacote é [`stackql-mcp-server`](https://pypi.org/project/stackql-mcp-server/) no PyPI.

### Docker

**Quando usar:** um runtime em contêiner ou isolado de outra forma. A imagem é multiarquitetura (amd64 e arm64).

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

Como configuração de cliente:

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

A imagem é [`stackql/stackql-mcp`](https://hub.docker.com/r/stackql/stackql-mcp) no Docker Hub.

### CI e workflows agênticos (GitHub Actions)

**Quando usar:** execute o servidor dentro de um job do GitHub Actions para que um agente possa consultar a sua nuvem - e, se você permitir, agir sobre ela - como parte da CI.

[`stackql/setup-stackql-mcp@v1`](https://github.com/marketplace/actions/setup-stackql-mcp-server) instala o binário e grava uma configuração de MCP (com o modo `read_only` por padrão). Passe essa configuração para [`anthropics/claude-code-action`](https://github.com/anthropics/claude-code-action) por meio de `claude_args`:

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

Consulte o [README da action](https://github.com/stackql/setup-stackql-mcp) para ver mais receitas agênticas (auditorias da nuvem, estimativas de custo etc.).

### MCP incorporado

**Quando usar:** você está criando uma aplicação agêntica e quer fazer o vendoring do servidor MCP no seu próprio binário - sem `npx`, sem instalação separada, sem dependência de runtime.

Bibliotecas nativas iniciam o binário `stackql` assinado via stdio por trás do cliente oficial do SDK MCP de cada linguagem, para que a sua aplicação tenha a mesma interface SQL governada para todos os providers do registro. Cada biblioteca usa `read_only` por padrão - a elevação para um modo com gravação é sempre explícita - e pode baixar e verificar o binário na primeira execução ou fazer o vendoring dele no seu build para gerar um único executável autocontido. A API completa de cada linguagem está na [referência de MCP incorporado](/mcp/embedded).

**Rust**

O crate `stackql-mcp` inicia o binário por trás de um cliente `rmcp`. A funcionalidade padrão `sidecar` baixa e verifica o binário na primeira execução; a funcionalidade `vendored` o incorpora com `include_bytes!` para gerar um único binário autocontido. 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?;
```

[Ver no GitHub](https://github.com/stackql/stackql-mcp-rs)
[Ver no crates.io](https://crates.io/crates/stackql-mcp)

Referência completa: [MCP incorporado: Rust](/mcp/embedded/rust).

**Go**

A biblioteca `stackql-mcp-go` inicia o binário por trás do cliente oficial do SDK MCP para Go. Faça o vendoring do binário com `go:embed` para gerar um único binário autocontido, ou deixe que a biblioteca o baixe e verifique na primeira execução. Inicia no modo `read_only` por padrão.

```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()
```

[Ver no GitHub](https://github.com/stackql/stackql-mcp-go)
[Ver no pkg.go.dev](https://pkg.go.dev/github.com/stackql/stackql-mcp-go)

Referência completa: [MCP incorporado: Go](/mcp/embedded/go).

**Kotlin / JVM**

A biblioteca `io.stackql:stackql-mcp` inicia o binário por trás do cliente oficial do SDK MCP para Kotlin, e um plugin complementar do Gradle integra a mesma inicialização a um build. Requer JDK 17 e 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
}
```

[Ver no GitHub](https://github.com/stackql/stackql-mcp-kotlin)

Referência completa: [MCP incorporado: Kotlin / JVM](/mcp/embedded/kotlin).

**.NET**

O pacote `StackQL.Mcp` inicia o binário por trás do cliente oficial do SDK MCP para C#. Usa sidecar por padrão, ou você pode fazer o vendoring do bundle como recurso de build para gerar um executável autocontido. Requer .NET 8 ou posterior.

```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();
```

[Ver no GitHub](https://github.com/stackql/stackql-mcp-dotnet)

Referência completa: [MCP incorporado: .NET / C#](/mcp/embedded/dotnet).

**Gleam**

A biblioteca `stackql_mcp` tem como alvo o runtime Erlang/BEAM e expõe o servidor como um processo filho OTP via `child_spec()`, para que ele possa ficar dentro da sua própria árvore de supervisão. Inicia no modo `read_only` por padrão.

```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)
```

[Ver no GitHub](https://github.com/stackql/stackql-mcp-gleam)

Referência completa: [MCP incorporado: Gleam](/mcp/embedded/gleam).

**Swift**

O pacote `stackql-mcp-swift` inicia o binário por trás do cliente oficial do SDK MCP para Swift. O binário `darwin-universal` é assinado com Developer ID e notarizado pela Apple, então você pode empacotá-lo dentro de um `.app` assinado e manter válida a notarização do aplicativo. Requer macOS 13+ e 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()
```

[Ver no GitHub](https://github.com/stackql/stackql-mcp-swift)

Referência completa: [MCP incorporado: Swift](/mcp/embedded/swift).

### Modelo de confiança

As mesmas propriedades de segurança valem para todos os canais:

- O binário `stackql` incorporado é assinado com Authenticode (Windows) e notarizado pela Apple (macOS).
- Cada bundle `.mcpb` é distribuído com uma soma de verificação SHA-256 publicada na página da versão.
- Os inicializadores `npx` e `uvx` verificam o SHA-256 do binário baixado antes do primeiro uso.
- A entrada no [MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=stackql) atesta os hashes de cada plataforma.

## Usar o GitHub Actions

As [GitHub Actions do StackQL](https://github.com/stackql/stackql-actions-demo) estão disponíveis para uso nos seus workflows do GitHub Actions. As seguintes actions estão disponíveis:

**stackql-deploy**

### `stackql-deploy`

Implante ou teste stacks de infraestrutura com o StackQL diretamente nos seus workflows do GitHub. Essa action possibilita workflows de infraestrutura como código (IaC) com uma sintaxe semelhante à SQL, o que permite definir, implantar e gerenciar recursos na nuvem em vários providers em um único workflow.  

[Ver no GitHub Marketplace](https://github.com/marketplace/actions/stackql-deploy)
[Ver no GitHub](https://github.com/stackql/stackql-deploy-action)

__Exemplo de uso__

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

Configure o StackQL no seu workflow do GitHub Actions.  

[Ver no GitHub Marketplace](https://github.com/marketplace/actions/setup-stackql)
[Ver no GitHub](https://github.com/stackql/setup-stackql)

__Exemplo de uso__

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

Instale o servidor MCP do StackQL no seu workflow do GitHub Actions.  A action instala o binário assinado e grava uma configuração `mcpServers` (com o modo `read_only` por padrão) que uma etapa agêntica, como `anthropics/claude-code-action`, consome via `claude_args`.

[Ver no GitHub Marketplace](https://github.com/marketplace/actions/setup-stackql-mcp-server)
[Ver no GitHub](https://github.com/stackql/setup-stackql-mcp)

__Exemplo de uso__

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

Execute comandos do StackQL no seu workflow do GitHub Actions.  As consultas podem ser fornecidas inline ou a partir de um arquivo no repositório.  

[Ver no GitHub Marketplace](https://github.com/marketplace/actions/stackql-exec)
[Ver no GitHub](https://github.com/stackql/stackql-exec)

__Exemplo de uso__

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

Execute testes unitários no seu workflow do GitHub Actions (para verificações de garantia, governança ou segurança na nuvem).  

[Ver no GitHub Marketplace](https://github.com/marketplace/actions/stackql-assert)
[Ver no GitHub](https://github.com/stackql/stackql-assert)

__Exemplo de uso__

```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 }}
```

## Outras bibliotecas

O StackQL oferece vários métodos de integração que permitem usá-lo em diferentes linguagens de programação e ambientes. Essas bibliotecas estendem a funcionalidade do StackQL e facilitam a incorporação da consulta e do gerenciamento de recursos na nuvem nas suas aplicações e workflows existentes.  

**pystackql**

### Pacote Python `pystackql`

Wrapper Python para usar o StackQL nos seus programas Python. O pacote `pystackql` está disponível no [__PyPI__](https://pypi.org/project/pystackql/), e a documentação do pacote `pystackql` está disponível no [__Read the Docs__](https://pystackql.readthedocs.io/en/latest/). Para instalar o pacote `pystackql`, execute o comando a seguir:

```bash
pip install pystackql
```

O exemplo a seguir mostra o pacote `pystackql` usado junto com o `pandas` para executar consultas do StackQL e retornar os resultados em um `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)
```
