Pular para o conteúdo principal
Página traduzida

Esta página foi traduzida do inglês com assistência de IA. Se houver diferenças entre as duas, a versão em inglês é a referência.

Instalação

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

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.

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

brew install stackql

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.

Claude Desktop​

A forma recomendada de instalar o servidor MCP do StackQL no Claude Desktop é pelo Anthropic Connector Directory (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.


informação

O servidor MCP do StackQL também está listado no Official MCP Registry como io.github.stackql/stackql-mcp.

dica

O bundle é uma das várias formas de executar o servidor MCP do StackQL. Consulte Usar o StackQL com o Claude Desktop para ver o passo a passo completo do Claude Desktop, ou Instalar o servidor MCP para as opções npx, Docker, Python, CI e manual.

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.

RegistroTipoPublicado viaListagemObservações
Official MCP RegistryRegistro canônico de metadadosCLI mcp-publisher + server.jsonmodelcontextprotocol.io/search
modelcontextprotocol.io/direct
anuncia todos os 8 pacotes (mcpb x5, oci, npm, pypi)
npmRegistro de pacotesnpm publish@stackql/mcp-serverinicializador npx
PyPIRegistro de pacotestwine uploadstackql-mcp-serverinicializador uvx / pip
Docker HubRegistro de contêineresdocker buildx --pushstackql/stackql-mcpmultiarquitetura amd64 + arm64
GitHub Actions MarketplaceMarketplace de CI (action setup-stackql-mcp)Repositório público + versão + listagem no marketplacesetup-stackql-mcp-serverPublicador verificado; stackql/setup-stackql-mcp

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 é 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. Cada bundle tem uma soma de verificação .sha256 correspondente na página da versão. Verifique-a e depois instale via Settings -> Extensions no Claude Desktop:

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

Consulte Usar o StackQL com o Claude Desktop 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.

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

npx (sem instalação)​

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

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

O inicializador @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.

{ "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 no PyPI.

Docker​

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

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

Como configuração de cliente:

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

A imagem é 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 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 por meio de 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__*'

Consulte o README da action 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.

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.

# 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?;

Referência completa: MCP incorporado: Rust.

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 atesta os hashes de cada plataforma.

Usar o GitHub Actions​

As GitHub Actions do StackQL estão disponíveis para uso nos seus workflows do GitHub Actions. As seguintes actions estão disponíveis:

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.


Exemplo de uso

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

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.

Pacote Python pystackql​

Wrapper Python para usar o StackQL nos seus programas Python. O pacote pystackql está disponível no PyPI, e a documentação do pacote pystackql está disponível no Read the Docs. Para instalar o pacote pystackql, execute o comando a seguir:

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:

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)