Azure-Assistant-MCP

Minimal, fast MCP server for exploring Azure using Azure Resource Graph (ARG). It generates and runs KQL to answer questions about your Azure environment(s), with clear, explicit scoping and optional management group coverage.

Disclaimer

Use this project at your own risk. It is provided "as is" without warranties or guarantees of any kind. You are solely responsible for how you use it, including configuration, access control, and compliance with your organization’s policies. The author and contributors are not liable for any damages, data loss, security incidents, costs, or policy violations that result from using this software. No employer or organization is implied to endorse or support this project.

Why this exists

• Make it trivial to inspect and run ARG KQL directly.
• Avoid heavyweight dependencies; ship a small, stdio-based MCP server.

Highlights

• Natural‑language → KQL for common tasks; always shows the query.
• Direct KQL execution against ARG with paging caps (top).
• Explicit scope in responses: tenant + subscriptions or management group.
• Auto‑discover subscriptions or query at management group scope.
• Optional diagnostics mode for quick scope debugging.

Requirements

• Python 3.10+
• Azure SPN(s) with Reader at the scope you intend to query:
  • Subscriptions: Reader on each target subscription
  • Management group: Reader on the MG (and underlying resources)

Install

• From the repo root:
  • pip install -e .
  • Or use the wrapper: ./azure-assistant-mcp.sh (prefers .venv if present)
• Add as an MCP stdio server in your client using the wrapper command.

  • Ensure the wrapper is executable: chmod +x ./azure-assistant-mcp.sh

  • Example (Claude Desktop CLI):

    claude mcp add azure-assistant-mcp \
      /your/path/Azure-Assistant-MCP/azure-assistant-mcp.sh \
      --env AZURE_ASSISTANT_CONFIG=/your/path/Azure-Assistant-MCP/azure-config.json \
      --scope user \
      --transport stdio
    

Configuration

• Place your secrets in azure-config.json (ignored by git). See azure-config-example.json for structure.
• The launch script exports AZURE_ASSISTANT_CONFIG to the repo’s azure-config.json to avoid accidental cross‑repo configs.
• You can also point to a custom location via AZURE_ASSISTANT_CONFIG.

Schema

• Top level
  • debug (optional): enables diagnostics tool
  • tenants: list of configured tenants
• Per tenant
  • id: tenant guid
  • name: friendly name
  • service_principal.client_id / service_principal.client_secret
  • default_subscription_id (optional fallback)
  • management_group_id (optional; short name like contoso-root or full resource id). The server normalizes to the short name.

Scoping Rules

• If subscription_ids are provided: use those subscriptions.
• Else if use_all_subscriptions is true and management_group_id is configured: run at MG scope in ARG.
• Else attempt to enumerate subscriptions via ARM and use that list.
• Else fall back to default_subscription_id.
• Responses always print Tenant and either Scope: managementGroup=... or Subscriptions used: N.

Tools

• ask-azure:

  • Input: { "question": string, "tenant_name?": string, "subscription_ids?": string[], "use_all_subscriptions?": boolean, "auto_execute?": boolean }
  • Generates KQL for your question. If auto_execute is true (default), executes it using Scoping Rules. If tenant_name is omitted, the server heuristically infers it from text (matches names and initialisms).

• list-tenants:

  • Input: {}
  • Lists configured tenants from azure-config.json with their IDs, optional management_group_id, and default_subscription_id to help you pick scope and SPN.

• run-arg-kql:

  • Input: { "kql_query": string, "tenant_name?": string, "subscription_ids?": string[], "use_all_subscriptions?": boolean, "top?": integer }
  • Executes provided KQL using Scoping Rules. Adds Rows, Tenant, and the scope line to the header.

• run-kql-template:

  • Input: { "template_name": string, "params?": object, "tenant_name?": string, "subscription_ids?": string[], "use_all_subscriptions?": boolean, "top?": integer }
  • Loads src/azure_assistant_mcp/kql/<template_name>.md (fenced kql) or .kql, applies simple {{key}} replacements from params, and executes with Scoping Rules.

• list-subscriptions:

  • Input: { "tenant_name?": string }
  • Lists subscriptions. Uses ARM enumeration when possible, enriches with ARG; prefers MG scope if configured to return a complete list.

• vm-count-by-tenant:

  • Input: { "tenant_names?": string[], "use_all_subscriptions?": boolean }
  • Runs a simple VM count per tenant using the Scoping Rules.

• diagnostics (shown only when debug is true):

  • Input: { "tenant_name?": string }
  • Prints config path, resolved tenant, normalized MG id, ARM enumeration sample and count, ARG MG coverage sample and count, and the default scoping decision.

• arg-tables:

  • Input: {}
  • Prints an overview of common Azure Resource Graph tables (resourcecontainers, resources, resourcechanges, advisorresources, healthresources, policyresources) with purposes and typical use cases.

• arg-examples:

  • Input: { "topic?": string } where topic can be subscriptions, resourcegroups, changes, containerchanges, advisor, health, or policy.
  • Returns sample KQL snippets for common scenarios across the ARG tables.

KQL Templates (customize queries)

• You can edit the KQL used by built-in tools and examples without touching Python code.
• Templates live in src/azure_assistant_mcp/kql/ as .md files with a fenced ```kql block (or plain .kql files).
• At runtime, the server loads these templates. There is no fallback: if a required template is missing, the server raises an error so you can fix it.
• Override the template directory by setting AZURE_ASSISTANT_KQL_PATH to another folder.
• Examples:
  • list_subscriptions.md
  • list_resource_groups.md
  • untagged_resource_groups.md
  • manual_changes.md
  • resource_changes_recent.md
  • stopped_vms.md
  • generic_list_resources.md
  • Create your own, e.g. kubernetes_inventory.md, then run with: run-kql-template { "template_name": "kubernetes_inventory", "params": { ... } }.

Usage Examples

• List subscriptions in a tenant by MG:
  • Tool: list-subscriptions
  • Input: { "tenant_name": "Contoso" }
• Count VMs across all subs in a tenant:
  • Tool: ask-azure
  • Input: { "tenant_name": "Contoso", "question": "How many virtual machines exist?" }
• Run KQL directly across all subs at MG scope:
  • Tool: run-arg-kql
  • Input: { "tenant_name": "Contoso", "kql_query": "resourcecontainers | where type =~ 'microsoft.resources/subscriptions' | project name, subscriptionId | order by name asc" }

Security

• Do not commit real credentials. azure-config.json is git‑ignored; use the example file as a template.
• Consider storing secrets in a secure store and templating your config.
• Ensure service principals have least privilege for the scopes you query.

Troubleshooting

• Seeing only one subscription:
  • Add a management_group_id that contains all target subscriptions, or pass subscription_ids explicitly.
• BadRequest from ARG:
  • Check KQL syntax and selected scope. Start with run-arg-kql using a small query and top.
• Validate scope quickly:
  • Enable debug: true and run the diagnostics tool for the tenant.

Development

• Code lives in src/azure_assistant_mcp/. Entry point is azure_assistant_mcp:main.
• Wrapper script: azure-assistant-mcp.sh (sets PYTHONPATH and pins AZURE_ASSISTANT_CONFIG).
• Backwards-compatibility alias: azure-assistant.sh (deprecated).
• Dependencies: mcp, python-dotenv, azure-identity, azure-mgmt-resourcegraph, azure-mgmt-subscription.

Claude Code

• Suggested sub-agent: Claude_Agents/azure-cloud-architect.md — an Azure cloud architecture helper you can load in Claude Code alongside this MCP server.
• Getting started:
  • Copy Claude_Agents/azure-cloud-architect.md into your .claude/agents folder

Contributing

• Issues and PRs welcome. Please omit real tenant IDs, secrets, or organization names from examples and logs.

License

• Licensed under Apache-2.0. See LICENSE for full terms.
• Attribution: This project includes a NOTICE file. Per Apache-2.0 §4(d), redistributors must retain the attribution notices in NOTICE in any source distributions and in documentation or about dialogs where such notices normally appear.

Commercial use & sponsorship

• Enterprise users are encouraged to attribute the project in documentation or about pages.
• If your organization benefits from this project, please consider sponsorship or a commercial support agreement.
• Options:
  • Commercial support/license inquiries: open an issue or contact the maintainer.
  •