Saltar al contenido principal
Página traducida

Esta página se tradujo del inglés con ayuda de IA. Si hay diferencias entre ambas, la versión en inglés es la referencia.

Instalación

Aquí se proporcionan las instrucciones para instalar StackQL en distintas plataformas.

macOS​

StackQL está disponible en macOS mediante Homebrew y el instalador pkg; se admiten tanto la arquitectura ARM (M1/Apple Silicon) como la AMD con un único instalador multiarquitectura.

Para instalar mediante Homebrew, ejecute el siguiente comando en su terminal:

brew install stackql

Usar con clientes MCP​

El servidor MCP de StackQL se ejecuta localmente sobre stdio, por lo que las credenciales de los providers permanecen en su equipo sea cual sea el cliente que use. Elija su cliente a continuación: cada pestaña presenta primero la vía del directorio o de un solo clic y la configuración manual como alternativa. Para ver todos los canales de distribución, incluidos npx, Python, Docker y CI, consulte Instalar el servidor MCP.

Claude Desktop​

La forma recomendada de instalar el servidor MCP de StackQL en Claude Desktop es desde el Anthropic Connector Directory (Settings -> Connectors -> Add -> Browse Connectors, busque StackQL) - Claude Desktop selecciona automáticamente el binario firmado correcto para su plataforma. Como alternativa, a cada versión de StackQL se adjuntan MCP Bundles precompilados (.mcpb) para instalar desde un archivo descargado - en ninguno de los dos casos se requiere una instalación de StackQL por separado. Los bundles están disponibles para macOS, Windows y Linux.

Las descargas de MCPB para Linux y Windows usan amd64 (x64) de forma predeterminada. Use los menús desplegables para seleccionar amd64 o arm64.

Descargar MCPB para macOS  
Descargar MCPB para Linux  
Descargar MCPB para Windows  

información

El servidor MCP de StackQL también figura en el Official MCP Registry como io.github.stackql/stackql-mcp.

consejo

El bundle es una de las varias formas de ejecutar el servidor MCP de StackQL. Consulte Usar StackQL con Claude Desktop para ver la guía paso a paso completa de Claude Desktop, o Instalar el servidor MCP para las opciones de npx, Docker, Python, CI y manual.

Instalar el servidor MCP​

El servidor MCP de StackQL permite a los agentes de IA consultar y aprovisionar recursos en la nube con StackQL. Se distribuye por varios canales - todos ejecutan el mismo servidor, así que elija el canal que se ajuste a su cliente y a sus requisitos de confianza. Las opciones siguientes se enumeran aproximadamente por orden de confianza y facilidad.

Marketplaces y directorios​

El servidor está publicado en el Official MCP Registry como io.github.stackql/stackql-mcp; los registros de paquetes siguientes contienen los artefactos distribuibles, y los directorios derivados toman la entrada de allí.

RegistroTipoPublicado medianteEntradaNotas
Official MCP RegistryRegistro canónico de metadatosCLI mcp-publisher + server.jsonmodelcontextprotocol.io/search
modelcontextprotocol.io/direct		anuncia los 8 paquetes (mcpb x5, oci, npm, pypi)
npmRegistro de paquetesnpm publish@stackql/mcp-serverlanzador npx
PyPIRegistro de paquetestwine uploadstackql-mcp-serverlanzador uvx / pip
Docker HubRegistro de contenedoresdocker buildx --pushstackql/stackql-mcpmultiarquitectura amd64 + arm64
GitHub Actions MarketplaceMarketplace de CI (acción setup-stackql-mcp)Repositorio público + versión + entrada del marketplacesetup-stackql-mcp-serverEditor verificado; stackql/setup-stackql-mcp

Bundle .mcpb precompilado​

Cuándo usarlo: Claude Desktop sin acceso al Connector Directory, o cuando quiere fijar una versión específica o verificar usted mismo las sumas de comprobación antes de instalar. Para la mayoría de los usuarios de Claude Desktop, el Anthropic Connector Directory es el método de instalación recomendado.

A cada versión de StackQL se adjunta un MCP Bundle precompilado para cada plataforma:

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

donde <platform> es darwin-universal, windows-x64 (AMD64), windows-arm64, linux-x64 o linux-arm64. Los botones de descarga de cada plataforma están en la pestaña Claude Desktop, en Usar con clientes MCP. Cada bundle tiene su suma de comprobación .sha256 correspondiente en la página de la versión. Verifíquela y después instale mediante Settings -> Extensions en Claude Desktop:

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

Consulte Usar StackQL con Claude Desktop para ver la guía paso a paso completa.

claude_desktop_config.json manual​

Cuándo usarlo: ya tiene el binario stackql en su PATH y usa Claude Desktop o cualquier otro cliente MCP stdio.

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

Los tres argumentos son imprescindibles:

  • --mcp.server.type=stdio selecciona el transporte stdio que usan los clientes integrados en editores.
  • --approot dirige la caché de providers a un directorio con permiso de escritura. Los clientes MCP pueden iniciar el servidor con el directorio de trabajo establecido en /, donde no se puede escribir.
  • --mcp.config '{"server": {"audit": {"disabled": true}}}' deshabilita el log de auditoría, que de lo contrario usa como directorio predeterminado el directorio de trabajo (en el que quizá no se pueda escribir).

Agregue las credenciales de los providers con un bloque "env" y ajuste el contrato de seguridad con "mode" - consulte Modos del servidor.

npx (sin instalación)​

Cuándo usarlo: cualquier entorno Node, cuando no quiere una instalación global de StackQL.

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

El lanzador @stackql/mcp-server descarga el binario stackql firmado en la primera ejecución, verifica su SHA-256 y lo guarda en caché para las ejecuciones posteriores.

uvx / pip (Python)​

Cuándo usarlo: un entorno Python - el mismo lanzador empaquetado para Python, que comparte la caché de binarios que llena el lanzador npx.

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

O instálelo en el entorno actual con pip install stackql-mcp-server (Python 3.9+). El paquete es stackql-mcp-server en PyPI.

Docker​

Cuándo usarlo: un runtime en contenedor o aislado de otra forma. La imagen es multiarquitectura (amd64 y arm64).

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

Como configuración de cliente:

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

La imagen es stackql/stackql-mcp en Docker Hub.

CI y workflows agénticos (GitHub Actions)​

Cuándo usarlo: ejecute el servidor dentro de un job de GitHub Actions para que un agente pueda consultar su nube (y, si usted lo permite, actuar sobre ella) como parte de la CI.

stackql/setup-stackql-mcp@v1 instala el binario y escribe una configuración de MCP (con el modo read_only de forma predeterminada). Pase esa configuración a anthropics/claude-code-action mediante 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 el README de la acción para ver más recetas agénticas (auditorías de nube, estimaciones de costos, etc.).

MCP integrado​

Cuándo usarlo: está creando una aplicación agéntica y quiere incorporar el servidor MCP a su propio binario mediante vendoring - sin npx, sin instalación por separado, sin dependencia de runtime.

Las bibliotecas nativas inician el binario stackql firmado sobre stdio detrás del cliente del SDK oficial de MCP de cada lenguaje, de modo que su aplicación obtiene la misma interfaz SQL gobernada para todos los providers del registro. Cada biblioteca usa read_only de forma predeterminada (el paso a un modo con escritura siempre es explícito) y puede descargar y verificar el binario en la primera ejecución o incorporarlo a su build mediante vendoring para obtener un único ejecutable autónomo. La API completa por lenguaje está en la referencia de MCP integrado.

El crate stackql-mcp inicia el binario detrás de un cliente rmcp. La funcionalidad predeterminada sidecar descarga y verifica el binario en la primera ejecución; la funcionalidad vendored lo integra con include_bytes! para obtener un único binario autónomo. 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?;
Ver en GitHub  
Ver en crates.io  

Referencia completa: MCP integrado: Rust.

Modelo de confianza​

Las mismas propiedades de seguridad se cumplen en todos los canales:

  • El binario stackql integrado está firmado con Authenticode (Windows) y notarizado por Apple (macOS).
  • Cada bundle .mcpb se distribuye con una suma de comprobación SHA-256 publicada en la página de la versión.
  • Los lanzadores npx y uvx verifican el SHA-256 del binario descargado antes del primer uso.
  • La entrada del MCP Registry certifica los hashes por plataforma.

Usar GitHub Actions​

Las GitHub Actions de StackQL están disponibles para usarlas en sus workflows de GitHub Actions. Están disponibles las siguientes acciones:

stackql-deploy​

Despliegue o pruebe stacks de infraestructura con StackQL directamente desde sus workflows de GitHub. Esta acción habilita workflows de infraestructura como código (IaC) con una sintaxis similar a SQL, lo que le permite definir, desplegar y gestionar recursos en la nube de varios providers en un único workflow.

Ver en GitHub Marketplace  
Ver en GitHub  

Ejemplo 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

Otras bibliotecas​

StackQL ofrece varios métodos de integración que permiten usarlo en distintos lenguajes de programación y entornos. Estas bibliotecas amplían la funcionalidad de StackQL y facilitan la incorporación de la consulta y la gestión de recursos en la nube a sus aplicaciones y workflows existentes.

Paquete de Python pystackql​

Wrapper de Python para usar StackQL en sus programas de Python. El paquete pystackql está disponible en PyPi; la documentación del paquete pystackql está disponible en Read the Docs. Para instalar el paquete pystackql, ejecute el siguiente comando:

pip install pystackql

El siguiente ejemplo muestra el paquete pystackql usado junto con pandas para ejecutar consultas de StackQL y devolver los resultados en un 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)