Skip to main content

How to use StackQL with Claude

Claude connects to StackQL through the Model Context Protocol: register stackql as an MCP server in Claude Desktop (or Claude Code), and Claude can inventory, audit, and - with your approval - modify cloud resources across every provider StackQL supports, driven by natural language.

Steps​

  1. Install StackQL and verify it is on your PATH:
stackql --version
  1. Edit the Claude Desktop configuration file:
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
  1. Add the server entry, including credentials for the providers you use:
{
  "mcpServers": {
    "stackql": {
      "command": "stackql",
      "args": [
        "mcp",
        "--mcp.server.type=stdio",
        "--mcp.config",
        "{\"server\": {\"transport\": \"stdio\", \"mode\": \"safe\"}}"
      ],
      "env": {
        "AWS_ACCESS_KEY_ID": "your-aws-access-key-id",
        "AWS_SECRET_ACCESS_KEY": "your-aws-secret-access-key",
        "STACKQL_GITHUB_USERNAME": "your-github-username",
        "STACKQL_GITHUB_PASSWORD": "your-github-personal-access-token"
      }
    }
  }
}

Include only the providers you need (AZURE_TENANT_ID/AZURE_CLIENT_ID/AZURE_CLIENT_SECRET for Azure, GOOGLE_CREDENTIALS for Google Cloud, DATABRICKS_CLIENT_ID/DATABRICKS_CLIENT_SECRET for Databricks). Never commit this file to version control.

  1. Restart Claude Desktop. The server starts automatically when a conversation begins.

  2. Ask in natural language. Examples that map directly to StackQL operations:

  • "List all EC2 instances in us-east-1 with public IP addresses"
  • "Which repositories in our GitHub org have branch protection disabled?"
  • "Create an S3 bucket named analytics-data in us-west-2"

For reads, Claude discovers the schema and runs SELECT statements immediately. For the bucket creation, safe mode triggers an approval prompt showing the exact INSERT before anything executes.

Controlling what Claude can do​

The mode field in the config is the contract: read_only for inventory-only assistants, safe (default) for approval-gated changes, delete_safe to allow create/update but gate deletes, full_access only for trusted automation. Every call Claude makes is recorded in the server's JSONL audit log regardless of mode.