Utiliser StackQL avec Claude Desktop

StackQL s'intègre à Claude Desktop via le Model Context Protocol (MCP), ce qui vous permet d'interroger et de provisionner des ressources cloud chez plusieurs fournisseurs cloud en langage naturel. Cette combinaison puissante vous permet d'interagir avec votre infrastructure cloud de manière conversationnelle tout en vous appuyant, en coulisses, sur l'interface SQL de StackQL.

Il existe trois options d'installation, présentées ici dans l'ordre recommandé : installer depuis le Connector Directory d'Anthropic, installer depuis un bundle téléchargé, ou enregistrer manuellement un binaire StackQL installé localement.

Installer depuis le Connector Directory (recommandé)

Le moyen le plus simple d'utiliser le serveur MCP StackQL avec Claude Desktop est de l'installer depuis le Connector Directory d'Anthropic. Dans Claude Desktop : Settings -> Connectors -> Add -> Browse Connectors, recherchez StackQL, puis cliquez sur Install. Il n'y a rien à télécharger et aucune installation séparée de StackQL n'est requise.

Vous pouvez aussi consulter la fiche directement sur claude.ai/directory.

Cette opération installe le serveur MCP StackQL en mode in-process pour votre plateforme : la fiche fournit un bundle multiplateforme combiné contenant des binaires signés pour macOS (universel), Windows x64, ainsi que Linux x64 et arm64, et Claude Desktop sélectionne automatiquement celui qui convient à votre machine. Pour Windows ARM64 natif, installez le bundle windows-arm64 distinct depuis les téléchargements ci-dessous. Les binaires Windows sont signés avec Authenticode et le binaire macOS est notarisé par Apple - ce sont les mêmes binaires que ceux de la version autonome de StackQL.

Un connecteur installé depuis le Connector Directory hérite de l'environnement de Claude Desktop ; définissez donc les variables d'environnement de vos providers au niveau du système d'exploitation avant de lancer Claude Desktop - consultez Identifiants propres à chaque provider. Claude Desktop capture son environnement au lancement : après avoir modifié des variables, vous devez quitter complètement Claude Desktop (y compris l'icône de la zone de notification sous Windows) puis le relancer. Demander à l'agent d'exécuter reload_credentials renvoie l'état des identifiants par provider et constitue le moyen le plus rapide de confirmer ce que le serveur voit et ne voit pas.

Claude Desktop annonce la capacité d'élicitation MCP ; le mode du serveur par défaut (safe) vous demande donc une approbation à chaque mutation - consultez Modes du serveur.

Installer depuis un bundle téléchargé

Utilisez cette option d'installation pour épingler une version précise, installer sans accès au Connector Directory ou vérifier vous-même les sommes de contrôle avant l'installation.

Le MCP Bundle préconstruit (.mcpb) est un paquet installable en un clic qui contient le binaire stackql signé et la configuration du serveur. Aucune installation séparée de StackQL n'est requise.

Téléchargez le bundle correspondant à votre plateforme depuis la dernière version :

Plateforme	Bundle
macOS (universel)	stackql-mcp-darwin-universal.mcpb
Windows AMD64 (x64)	stackql-mcp-windows-x64.mcpb
Windows ARM64 (natif)	stackql-mcp-windows-arm64.mcpb
Linux x64	stackql-mcp-linux-x64.mcpb
Linux arm64	stackql-mcp-linux-arm64.mcpb

Ensuite, dans Claude Desktop : Settings -> Extensions -> Install Extension, puis sélectionnez le fichier téléchargé. Le binaire embarqué est signé avec Authenticode (Windows) et notarisé par Apple (macOS) ; chaque bundle est accompagné d'une somme de contrôle .sha256 sur la page de la version. Pour vérifier avant l'installation :

# macOS / Linux
shasum -a 256 -c stackql-mcp-darwin-universal.mcpb.sha256

Le serveur est également référencé dans le MCP Registry officiel sous le nom io.github.stackql/stackql-mcp, qui épingle ces sommes de contrôle.

Configuration manuelle

Si StackQL est déjà installé, vous pouvez enregistrer le serveur MCP StackQL directement dans le fichier de configuration de Claude Desktop.

Prérequis

Avant de configurer StackQL avec Claude Desktop, vérifiez que vous disposez des éléments suivants :

1. StackQL installé - Téléchargez et installez StackQL depuis stackql.io ou utilisez un gestionnaire de paquets
2. Claude Desktop - Téléchargez-le depuis le site d'Anthropic
3. Identifiants des fournisseurs cloud - Clés d'API ou identifiants des fournisseurs cloud avec lesquels vous souhaitez travailler

Vérifiez que StackQL figure dans le PATH de votre système en exécutant :

stackql --version

Configurer le serveur MCP

Pour que Claude Desktop puisse communiquer avec StackQL, vous devez configurer le serveur MCP dans votre fichier de configuration Claude Desktop.

Windows

Modifiez le fichier de configuration situé à l'emplacement suivant :

%APPDATA%\Claude\claude_desktop_config.json

macOS

Modifiez le fichier de configuration situé à l'emplacement suivant :

~/Library/Application Support/Claude/claude_desktop_config.json

Linux

Modifiez le fichier de configuration situé à l'emplacement suivant :

~/.config/Claude/claude_desktop_config.json

Exemple de configuration

Ajoutez la configuration suivante à votre fichier claude_desktop_config.json :

{
  "mcpServers": {
    "stackql": {
      "command": "stackql",
      "args": [
        "mcp",
        "--mcp.server.type=stdio",
        "--tls.allowInsecure"
      ],
      "env": {
        "GOOGLE_CREDENTIALS": "/path/to/google-credentials.json",
        "AWS_ACCESS_KEY_ID": "your-aws-access-key-id",
        "AWS_SECRET_ACCESS_KEY": "your-aws-secret-access-key",
        "AZURE_CLIENT_ID": "your-azure-client-id",
        "AZURE_CLIENT_SECRET": "your-azure-client-secret",
        "AZURE_TENANT_ID": "your-azure-tenant-id",
        "DATABRICKS_CLIENT_ID": "your-databricks-client-id",
        "DATABRICKS_CLIENT_SECRET": "your-databricks-client-secret",
        "OPENAI_API_KEY": "your-openai-api-key"
      }
    }
  }
}

astuce

Vous n'avez besoin d'inclure que les variables d'environnement des fournisseurs cloud que vous comptez utiliser. Supprimez de la configuration les identifiants des providers inutilisés.

attention

N'ajoutez jamais votre fichier claude_desktop_config.json contenant de vrais identifiants à un système de gestion de versions. Appliquez des pratiques sécurisées de gestion des identifiants.

Claude Desktop annonce la capacité d'élicitation MCP ; le mode du serveur par défaut (safe) vous demande donc une approbation à chaque mutation. Passez à mode: read_only pour un accès limité à l'inventaire ou à mode: full_access pour désactiver les demandes d'approbation - consultez Modes du serveur.

Utiliser un fichier d'identifiants (--env.file)

Une alternative au bloc env - et celle qui est recommandée sous Windows - consiste à conserver les identifiants dans un fichier de type dotenv et à le transmettre avec l'option --env.file :

{
  "mcpServers": {
    "stackql": {
      "command": "stackql",
      "args": [
        "mcp",
        "--mcp.server.type=stdio",
        "--tls.allowInsecure",
        "--env.file=C:\\Users\\me\\stackql-credentials.env"
      ]
    }
  }
}

Avec un fichier d'identifiants minimal :

# stackql-credentials.env
GOOGLE_CREDENTIALS=/path/to/google-credentials.json
AWS_ACCESS_KEY_ID=your-aws-access-key-id
AWS_SECRET_ACCESS_KEY=your-aws-secret-access-key

Pourquoi cette approche est préférable au bloc env :

• Les modifications du bloc env nécessitent un redémarrage complet de Claude Desktop (y compris la fermeture de l'icône de la zone de notification) avant que le sous-processus MCP ne les voie, et sous Windows setx écrit dans le registre - la modification n'atteint jamais le processus Desktop en cours d'exécution.
• Le fichier --env.file peut être créé ou renouvelé à tout moment - il n'a même pas besoin d'exister au démarrage du serveur - et demander à l'agent d'exécuter reload_credentials prend en compte les modifications sans aucun redémarrage.

remarque

--env.file et reload_credentials sont disponibles dans les versions de StackQL postérieures à v0.10.542.

Identifiants propres à chaque provider

Les méthodes d'authentification diffèrent selon le fournisseur cloud ; consultez la documentation des providers (https://stackql.io/providers) pour connaître les variables d'environnement requises par le ou les providers souhaités.

Redémarrer Claude Desktop

Après avoir mis à jour le fichier de configuration, redémarrez Claude Desktop pour charger la nouvelle configuration du serveur MCP. Le serveur MCP StackQL démarre automatiquement lorsque vous commencez une nouvelle conversation.

Ce que vous pouvez faire

Une fois la configuration terminée, vous pouvez utiliser le langage naturel dans Claude Desktop pour :

Interroger des ressources cloud

Demandez à Claude de récupérer des informations sur votre infrastructure cloud :

• "Montre-moi toutes mes instances de calcul GCP dans la région us-central1"
• "Liste tous les buckets S3 de mon compte AWS"
• "Quelles machines virtuelles Azure sont en cours d'exécution dans mon abonnement ?"
• "Montre-moi tous les pods Kubernetes de l'espace de noms default"

Provisionner des ressources

Créez et déployez des ressources cloud à l'aide de commandes conversationnelles :

• "Crée un bucket S3 nommé 'my-data-bucket' dans us-west-2"
• "Déploie un bucket GCP Cloud Storage avec la gestion des versions activée"
• "Lance une petite instance EC2 dans us-east-1"
• "Crée un groupe de ressources Azure dans westus2"

Analyser et auditer

Réalisez des audits de sécurité et des contrôles de conformité :

• "Montre-moi tous les buckets S3 accessibles publiquement"
• "Liste les utilisateurs IAM qui ne se sont pas connectés depuis 90 jours"
• "Trouve toutes les instances GCP sans labels appropriés"
• "Identifie les VM Azure dont la sauvegarde n'est pas activée"

Opérations multicloud

Interrogez et comparez des ressources chez plusieurs fournisseurs cloud :

• "Montre-moi toutes les instances de calcul sur AWS, GCP et Azure"
• "Compare les coûts de stockage entre AWS S3 et GCP Cloud Storage"
• "Liste toutes les bases de données de tous les fournisseurs cloud"

Infrastructure as code

Générez et exécutez des requêtes de déploiement d'infrastructure :

• "Crée une stack de ressources comprenant un VPC, un sous-réseau et une instance EC2"
• "Déploie un cluster GKE complet avec des pools de nœuds"
• "Mets en place un déploiement multirégion dans AWS"

Modifier des ressources

Mettez à jour des ressources cloud existantes :

• "Ajoute des tags à toutes les instances EC2 qui n'en ont pas"
• "Active le chiffrement du bucket S3 'my-bucket'"
• "Mets à jour le type de machine de l'instance GCP 'web-server-1'"
• "Passe l'ACL de mon bucket Cloud Storage en privé"

Supprimer des ressources

Supprimez les ressources cloud dont vous n'avez plus besoin :

• "Supprime le bucket S3 'temp-bucket'"
• "Supprime toutes les instances EC2 arrêtées"
• "Nettoie les disques GCP inutilisés"

Exemple de conversation

Voici un exemple d'interaction avec Claude Desktop à l'aide de StackQL :

Vous : "Peux-tu me montrer toutes mes instances de calcul GCP ?"

Claude : Exécute une requête StackQL et renvoie les résultats dans un tableau mis en forme indiquant les noms des instances, les zones, les types de machine et l'état

Vous : "Crée un nouveau bucket Cloud Storage nommé 'analytics-data-2025' dans la région us-central1 avec un accès uniforme au niveau du bucket"

Claude : Exécute une instruction StackQL INSERT pour créer le bucket et confirme la création

Vous : "Liste maintenant tous mes buckets Cloud Storage"

Claude : Exécute une requête SELECT et affiche tous les buckets, y compris celui qui vient d'être créé

Astuces et bonnes pratiques

1. Soyez précis : plus votre demande est précise, meilleurs sont les résultats. Indiquez si possible les noms des ressources, les régions et des attributs précis.

2. Utilisez le langage naturel : vous n'avez pas besoin de connaître la syntaxe SQL - Claude traduit vos demandes en langage naturel en requêtes StackQL.

3. Vérifiez avant d'exécuter : pour les opérations destructives (DELETE, UPDATE), Claude vous montre généralement ce qui va être exécuté avant de poursuivre.

4. Opérations en plusieurs étapes : vous pouvez enchaîner des opérations au sein d'une même conversation. Claude conserve le contexte tout au long de la session.

5. Gestion des erreurs : si une requête échoue, Claude peut vous aider à diagnostiquer le problème et proposer des corrections à partir du message d'erreur.

6. Explorez les possibilités : demandez à Claude "Que puis-je faire avec StackQL ?" pour obtenir des suggestions adaptées à vos providers configurés.

Dépannage

Le serveur MCP ne démarre pas

Si Claude Desktop ne parvient pas à se connecter au serveur MCP StackQL :

1. Vérifiez que StackQL figure dans votre PATH
2. Vérifiez que votre fichier claude_desktop_config.json est un JSON valide
3. Assurez-vous que le chemin du fichier dans la configuration est correct pour votre système d'exploitation
4. Recherchez d'éventuels messages d'erreur dans les journaux de Claude Desktop

Erreurs d'authentification

Si vous recevez des erreurs d'authentification :

1. Vérifiez que les identifiants de votre fournisseur cloud sont corrects
2. Assurez-vous que les fichiers d'identifiants existent aux chemins indiqués
3. Vérifiez que les variables d'environnement sont correctement formatées dans la configuration - demander à l'agent d'exécuter reload_credentials renvoie l'état des identifiants par provider et constitue le moyen le plus rapide de voir quelle variable manque
4. Confirmez que vos identifiants disposent des permissions nécessaires

Erreurs de permission

Si des opérations échouent en raison de permissions insuffisantes :

1. Vérifiez que votre compte de service ou votre utilisateur IAM dispose des permissions requises
2. Vérifiez les politiques IAM propres à chaque provider
3. Assurez-vous que les services d'API sont activés dans vos projets cloud

En savoir plus

• Référence de la commande MCP de StackQL
• StackQL Provider Registry
• Spécification du langage
• Documentation du Model Context Protocol

Considérations de sécurité

attention

• Stockez les identifiants de manière sécurisée et ne les ajoutez jamais à un système de gestion de versions
• Appliquez le principe du moindre privilège aux comptes de service
• Renouvelez régulièrement les identifiants et les clés d'API
• Surveillez les journaux du serveur MCP pour détecter toute activité inhabituelle
• Envisagez d'utiliser les outils de gestion des identifiants des fournisseurs cloud (par exemple Secret Manager, Parameter Store)