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.

Azure-Assistant-MCP

Disclaimer

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.

Azure Assistant MCP

Azure-Assistant-MCP

Disclaimer

Why this exists

Highlights

Requirements

Install

Configuration

Schema

Scoping Rules

Tools

KQL Templates (customize queries)

Usage Examples

Security

Troubleshooting

Development

Claude Code

Contributing

License

Commercial use & sponsorship

Azure-Assistant-MCP

Disclaimer

Why this exists

Highlights

Requirements

Install

Configuration

Schema

Scoping Rules

Tools

KQL Templates (customize queries)

Usage Examples

Security

Troubleshooting

Development

Claude Code

Contributing

License

Commercial use & sponsorship