Aller au contenu principal
Page traduite

Cette page a été traduite de l'anglais avec l'aide de l'IA. En cas de divergence, la version anglaise fait référence.

Installation

Les instructions d'installation de StackQL sur différentes plateformes sont fournies ici.

macOS​

StackQL est disponible sur macOS via Homebrew et le programme d'installation pkg ; les architectures ARM (M1/Apple Silicon) et AMD sont toutes deux prises en charge par un seul programme d'installation multi-architecture.

Pour installer StackQL via Homebrew, exécutez la commande suivante dans votre terminal :

brew install stackql

Utiliser avec des clients MCP​

Le serveur MCP StackQL s'exécute localement via stdio : les identifiants des providers restent donc sur votre machine, quel que soit le client utilisé. Choisissez votre client ci-dessous : chaque onglet indique d'abord l'installation depuis l'annuaire ou en un clic, puis la configuration manuelle comme solution de repli. Pour tous les canaux de distribution, y compris npx, Python, Docker et la CI, consultez Installer le serveur MCP.

Claude Desktop​

La méthode recommandée pour installer le serveur MCP StackQL dans Claude Desktop passe par l'Anthropic Connector Directory (Settings -> Connectors -> Add -> Browse Connectors, recherchez StackQL) - Claude Desktop sélectionne automatiquement le binaire signé adapté à votre plateforme. Sinon, des MCP Bundles précompilés (.mcpb) sont joints à chaque version de StackQL pour une installation depuis un fichier téléchargé - dans les deux cas, aucune installation séparée de StackQL n'est nécessaire. Des bundles sont disponibles pour macOS, Windows et Linux.

Les téléchargements MCPB pour Linux et Windows utilisent amd64 (x64) par défaut. Utilisez les listes déroulantes pour sélectionner amd64 ou arm64.

Télécharger le MCPB macOS  
Télécharger le MCPB Linux  
Télécharger le MCPB Windows  

info

Le serveur MCP StackQL est également référencé dans l'Official MCP Registry sous le nom io.github.stackql/stackql-mcp.

astuce

Le bundle est l'une des différentes façons d'exécuter le serveur MCP StackQL. Consultez Utiliser StackQL avec Claude Desktop pour le guide pas à pas complet de Claude Desktop, ou Installer le serveur MCP pour les options npx, Docker, Python, CI et manuelle.

Installer le serveur MCP​

Le serveur MCP StackQL permet aux agents IA d'interroger et de provisionner des ressources cloud avec StackQL. Il est distribué par plusieurs canaux - tous exécutent le même serveur, choisissez donc le canal qui correspond à votre client et à vos exigences de confiance. Les options ci-dessous sont classées approximativement par ordre de confiance et de facilité.

Marketplaces et annuaires​

Le serveur est publié dans l'Official MCP Registry sous le nom io.github.stackql/stackql-mcp ; les registres de paquets ci-dessous hébergent les artefacts distribuables, et les annuaires en aval reprennent la fiche à partir de là.

RegistreTypePublié viaFicheRemarques
Official MCP RegistryRegistre de métadonnées canoniqueCLI mcp-publisher + server.jsonmodelcontextprotocol.io/search
modelcontextprotocol.io/direct		annonce les 8 paquets (mcpb x5, oci, npm, pypi)
npmRegistre de paquetsnpm publish@stackql/mcp-serverlanceur npx
PyPIRegistre de paquetstwine uploadstackql-mcp-serverlanceur uvx / pip
Docker HubRegistre de conteneursdocker buildx --pushstackql/stackql-mcpmulti-architecture amd64 + arm64
GitHub Actions MarketplaceMarketplace CI (action setup-stackql-mcp)Dépôt public + version + fiche marketplacesetup-stackql-mcp-serverÉditeur vérifié ; stackql/setup-stackql-mcp

Bundle .mcpb précompilé​

Quand l'utiliser : Claude Desktop sans accès au Connector Directory, ou lorsque vous voulez épingler une version précise ou vérifier vous-même les sommes de contrôle avant l'installation. Pour la plupart des utilisateurs de Claude Desktop, l'Anthropic Connector Directory est la méthode d'installation recommandée.

Un MCP Bundle précompilé est joint à chaque version de StackQL pour chaque plateforme :

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

où <platform> vaut darwin-universal, windows-x64 (AMD64), windows-arm64, linux-x64 ou linux-arm64. Les boutons de téléchargement de chaque plateforme se trouvent dans l'onglet Claude Desktop sous Utiliser avec des clients MCP. Chaque bundle a une somme de contrôle .sha256 correspondante sur la page de la version. Vérifiez-la, puis installez le bundle via Settings -> Extensions dans Claude Desktop :

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

Consultez Utiliser StackQL avec Claude Desktop pour le guide pas à pas complet.

Configuration manuelle de claude_desktop_config.json​

Quand l'utiliser : vous avez déjà le binaire stackql dans votre PATH et utilisez Claude Desktop ou tout autre client MCP stdio.

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

Les trois arguments sont indispensables :

  • --mcp.server.type=stdio sélectionne le transport stdio qu'utilisent les clients intégrés aux éditeurs.
  • --approot fait pointer le cache des providers vers un répertoire accessible en écriture. Les clients MCP peuvent lancer le serveur avec / comme répertoire de travail, qui n'est pas accessible en écriture.
  • --mcp.config '{"server": {"audit": {"disabled": true}}}' désactive le journal d'audit, dont le répertoire par défaut est sinon le répertoire de travail (éventuellement non accessible en écriture).

Ajoutez les identifiants des providers avec un bloc "env" et ajustez le contrat de sécurité avec "mode" - consultez Modes du serveur.

npx (sans installation)​

Quand l'utiliser : tout environnement Node, lorsque vous ne voulez pas d'installation globale de StackQL.

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

Le lanceur @stackql/mcp-server télécharge le binaire stackql signé au premier lancement, vérifie son SHA-256 et le met en cache pour les lancements suivants.

uvx / pip (Python)​

Quand l'utiliser : un environnement Python - le même lanceur, empaqueté pour Python, qui partage le cache de binaires alimenté par le lanceur npx.

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

Ou installez-le dans l'environnement courant avec pip install stackql-mcp-server (Python 3.9+). Le paquet est stackql-mcp-server sur PyPI.

Docker​

Quand l'utiliser : un runtime conteneurisé ou isolé d'une autre manière. L'image est multi-architecture (amd64 et arm64).

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

Sous forme de configuration client :

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

L'image est stackql/stackql-mcp sur Docker Hub.

CI et workflows agentiques (GitHub Actions)​

Quand l'utiliser : exécuter le serveur dans un job GitHub Actions pour qu'un agent puisse interroger votre cloud - et, si vous l'autorisez, agir dessus - dans le cadre de la CI.

stackql/setup-stackql-mcp@v1 installe le binaire et écrit une configuration MCP (en mode read_only par défaut). Transmettez cette configuration à anthropics/claude-code-action via 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__*'

Consultez le README de l'action pour d'autres recettes agentiques (audits cloud, estimations de coûts, etc.).

MCP embarqué​

Quand l'utiliser : vous développez une application agentique et voulez embarquer le serveur MCP dans votre propre binaire - pas de npx, pas d'installation séparée, pas de dépendance à l'exécution.

Des bibliothèques natives lancent le binaire stackql signé via stdio derrière le client du SDK MCP officiel de chaque langage : votre application obtient ainsi la même interface SQL gouvernée vers chaque provider du registre. Chaque bibliothèque utilise read_only par défaut - le passage à un mode autorisant l'écriture est toujours explicite - et peut soit télécharger et vérifier le binaire au premier lancement, soit l'embarquer dans votre build pour obtenir un exécutable unique et autonome. L'API complète de chaque langage figure dans la référence du MCP embarqué.

La crate stackql-mcp lance le binaire derrière un client rmcp. La fonctionnalité sidecar, activée par défaut, télécharge et vérifie le binaire au premier lancement ; la fonctionnalité vendored l'embarque avec include_bytes! pour obtenir un binaire unique et autonome. 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?;
Voir sur GitHub  
Voir sur crates.io  

Référence complète : MCP embarqué : Rust.

Modèle de confiance​

Les mêmes propriétés de sécurité s'appliquent à tous les canaux :

  • Le binaire stackql embarqué est signé Authenticode (Windows) et notarisé par Apple (macOS).
  • Chaque bundle .mcpb est accompagné d'une somme de contrôle SHA-256 publiée sur la page de la version.
  • Les lanceurs npx et uvx vérifient le SHA-256 du binaire téléchargé avant la première utilisation.
  • L'entrée du MCP Registry atteste les empreintes de chaque plateforme.

Utiliser GitHub Actions​

Des actions GitHub StackQL sont disponibles pour vos workflows GitHub Actions. Les actions suivantes sont disponibles :

stackql-deploy​

Déployez ou testez des stacks d'infrastructure avec StackQL directement depuis vos workflows GitHub. Cette action permet des workflows d'infrastructure as code (IaC) avec une syntaxe proche de SQL, pour définir, déployer et gérer des ressources cloud de plusieurs providers dans un seul workflow.

Voir sur GitHub Marketplace  
Voir sur GitHub  

Exemple d'utilisation

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

Autres bibliothèques​

StackQL propose plusieurs méthodes d'intégration qui permettent de l'utiliser dans différents langages de programmation et environnements. Ces bibliothèques étendent les fonctionnalités de StackQL et facilitent l'intégration de l'interrogation et de la gestion des ressources cloud dans vos applications et workflows existants.

Paquet Python pystackql​

Wrapper Python pour utiliser StackQL dans vos programmes Python. Le paquet pystackql est disponible sur PyPi ; la documentation du paquet pystackql est disponible sur Read the Docs. Pour installer le paquet pystackql, exécutez la commande suivante :

pip install pystackql

L'exemple suivant montre le paquet pystackql utilisé avec pandas pour exécuter des requêtes StackQL et renvoyer les résultats dans 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)