Skip to main content

Azure Scout: az-scout

CI Publish to PyPI Publish Container Image PyPI version Downloads License

Scout Azure regions for VM availability, zone mappings, pricing, spot scores, and quota — then plan deployments with confidence.

📖 Full documentation: docs.az-scout.com

📦 Plugin catalog: docs.az-scout.com/catalog

az-scout helps Azure operators and architects answer the questions that matter when planning resilient, cost-efficient VM deployments:

  • Do my subscriptions share the same physical datacenter for logical zone 1?
  • Which VM SKUs are available in all three zones with headroom in my quota?
  • What is the Spot placement likelihood for this SKU family right now?
  • Which deployment plan gives me the best confidence score across zones?

All from a single web UI — or through an MCP-powered AI agent connected to your favourite tools (Claude, VS Code Copilot, etc.).

az-scout web UI showing zone mappings and SKU availability

Quick start

Prerequisites

Requirement Details
Python ≥ 3.11
Azure credentials Any method supported by DefaultAzureCredential (az login, managed identity, …)
RBAC Reader on the subscriptions you want to query, Virtual Machine Contributor on the subscriptions for Spot Placement Scores retrieval
Azure OpenAI (optional) For the AI Chat Assistant: set AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_DEPLOYMENT (optionally AZURE_OPENAI_API_VERSION). AZURE_OPENAI_API_KEY is optional — without it, keyless Microsoft Entra ID auth is used (the identity needs Cognitive Services OpenAI User, or Azure AI User for Foundry, on the AI resource)
# Make sure you are authenticated to Azure
az login

# Run the tool (no install required)
uvx az-scout

Your browser opens automatically at http://127.0.0.1:5001.

Plugins

az-scout can be extended with pip-installable plugins discovered automatically at startup. See docs/PLUGINS.md for the plugin development guide and the scaffold for a ready-to-use template.

A Plugin Manager is included in the UI to browse the plugin catalog, install, update, and remove plugins.

Installation options

uv install az-scout
uvx az-scout

Alternative: install az-scout with pip

pip install az-scout
az-scout

Docker

docker run --rm -p 8000:8000 \
  -e AZURE_TENANT_ID=<your-tenant> \
  -e AZURE_CLIENT_ID=<your-sp-client-id> \
  -e AZURE_CLIENT_SECRET=<your-sp-secret> \
  ghcr.io/az-scout/az-scout:latest

Dev Container

A Dev Container configuration is included for a one-click development environment. Requires Docker and VS Code with the Dev Containers extension.

Open the repo in VS Code → Reopen in Container → run uv run az-scout web --host 0.0.0.0 --port 5001 --reload --no-open -v.

Azure Container App

It is also possible to deploy az-scout as a web app in Azure using the provided Bicep template (see Deploy to Azure section below).

Note: The web UI is designed for local use and may not be suitable for public-facing deployment without additional security measures (authentication, network restrictions, etc.). The MCP server can be exposed over the public internet if needed, but ensure you have proper authentication and authorization in place to protect access to Azure data.

UI guided deployment

Deploy to Azure

A Bicep template is provided to deploy az-scout as an Azure Container App with a managed identity. You can use the Deploy to Azure button above for a portal-guided experience, or use the CLI commands below.

Resources created

The deployment creates:

Resource Purpose
Container App Runs ghcr.io/az-scout/az-scout
Managed Identity Reader role on target subscriptions
VM Contributor Virtual Machine Contributor role for Spot Placement Scores (enabled by default)
Log Analytics Container logs and diagnostics
Container Apps Env Hosting environment

Note: The Virtual Machine Contributor role is required for querying Spot Placement Scores (POST endpoint). Set enableSpotScoreRole=false to skip this if you don't need spot scores or prefer to manage permissions manually.

Usage

CLI options

az-scout [COMMAND] [OPTIONS]

az-scout --help.     # show global help
az-scout web --help  # show web subcommand help
az-scout mcp --help  # show mcp subcommand help
az-scout chat --help # show chat subcommand help
az-scout --version   # show version

az-scout web (default)

Run the web UI. This is the default when no subcommand is given.

  --host TEXT     Host to bind to.  [default: 127.0.0.1]
  --port INTEGER  Port to listen on.  [default: 5001]
  --no-open       Don't open the browser automatically.
  -v, --verbose   Enable verbose logging.
  --reload        Auto-reload on code changes (development only).
  --help          Show this message and exit.

az-scout mcp

Run the MCP server.

  --http          Use Streamable HTTP transport instead of stdio.
  --port INTEGER  Port for Streamable HTTP transport.  [default: 8080]
  -v, --verbose   Enable verbose logging.
  --help          Show this message and exit.

az-scout chat

Interactive AI chat in the terminal. Requires Azure OpenAI credentials.

# Start an interactive session
az-scout chat

# One-shot query
az-scout chat "What SKUs are available in francecentral?"
  -v, --verbose   Enable verbose logging.
  --help          Show this message and exit.

Slash commands are available during the chat session:

Command Description
/help Show available commands
/context Show current tenant, subscription, region, and mode
/tenant [id] Switch tenant (interactive picker or direct)
/subscription [id] Switch subscription (interactive picker or direct)
/region [name] Switch region (interactive picker or direct)
/mode [name] Switch chat mode (discussion, planner, …)
/tenants List accessible tenants
/subscriptions List enabled subscriptions
/regions List AZ-enabled regions
/clear Clear conversation history
/new Start a new session (re-select tenant, clear history)
/exit Exit (or press Ctrl+D)

MCP server

An MCP server is included, allowing AI agents (Claude Desktop, VS Code Copilot, etc.) to query zone mappings and SKU availability directly.

Available tools

Tool Description
list_tenants Discover Azure AD tenants and authentication status
list_subscriptions List enabled subscriptions (optionally scoped to a tenant)
list_regions List regions that support Availability Zones
get_zone_mappings Get logical→physical zone mappings for subscriptions in a region
get_sku_availability Get VM SKU availability per zone with restrictions, capabilities, quota, and deployment confidence
get_spot_scores Get Spot Placement Scores (High / Medium / Low) for a list of VM sizes in a region
get_sku_deployment_confidence Compute Deployment Confidence Scores (0–100) for one or more VM SKUs with full signal breakdown
get_sku_pricing_detail Get detailed Linux pricing (PayGo, Spot, RI 1Y/3Y, SP 1Y/3Y) and VM profile for a single SKU

Plugin tools: Plugins can register additional MCP tools. For example, the Strategy Advisor plugin adds a capacity_strategy tool.

API

API documentation is available at /docs (Swagger UI) and /redoc (ReDoc) when the server is running.

License

MIT

Disclaimer

This tool is not affiliated with Microsoft. All capacity, pricing, and latency information are indicative and not a guarantee of deployment success. Spot placement scores are probabilistic. Quota values and pricing are dynamic and may change between planning and actual deployment. Latency values are based on Microsoft published statistics and must be validated with in-tenant measurements.

Metadata

Release files for az-scout 2026.11.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for az-scout 2026.11.0
File Size Uploaded Provenance Actions
az_scout-2026.11.0.tar.gz 2.0 MB With provenance Details for az_scout-2026.11.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for az-scout 2026.11.0
File Interpreter ABI Platform Actions
az_scout-2026.11.0-py3-none-any.whl Python 3 none any Details for az_scout-2026.11.0-py3-none-any.whl

Total release size: 2.7 MB

Release files / az_scout-2026.11.0.tar.gz

Download URL az_scout-2026.11.0.tar.gz
Size 2.0 MB
Tags Source
SHA-256 checksum
How to use checksums
df580146f43ea2f143aabbda44980dc41216de0c23f94f05ee058e4090fd8dfb
BLAKE2b-256 checksum
How to use checksums
8005e3963bea7d61d8d757beb3568c99f1d6ae58e78d35d9aa343fdb2cb07229
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / az_scout-2026.11.0-py3-none-any.whl

Download URL az_scout-2026.11.0-py3-none-any.whl
Size 773.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f7f84cfd099b9aee1bf233e0197bbe03f5b8f8b7e5212a6d60f5f4dee1b71e81
BLAKE2b-256 checksum
How to use checksums
a28d615999d3c6e4a155910721b9ea543c33e4cfac9091b83c9ee0534ca3361a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for az-scout 2026.11.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for az_scout-2026.11.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page