Azure Assistant

Minimal, fast MCP server that translates natural language Azure questions into ARG KQL with explicit tenant/subscription or MG scope.

python

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "iosdevil-azure-assistant-mcp": {
      "command": "./azure-assistant-mcp.sh",
      "args": [
        "--env",
        "AZURE_ASSISTANT_CONFIG=/your/path/Azure-Assistant-MCP/azure-config.json",
        "--scope",
        "user",
        "--transport",
        "stdio"
      ],
      "env": {
        "AZURE_ASSISTANT_CONFIG": "path/to/azure-config.json"
      }
    }
  }
}

This is a lightweight MCP server that translates natural language questions about Azure into direct Azure Resource Graph KQL queries. It runs locally, minimizes dependencies, and clearly scopes results to your tenant, subscriptions, or management group so you can inspect Azure environments quickly and safely.

How to use

You connect an MCP client to the server as a stdio server using the provided wrapper script. Once connected, you can ask questions in natural language and have them translated into KQL that runs against ARG with explicit scope. The server will return results with a clear header showing your tenant and the scope used (subscription-based or management group-based). Use the available tools to list tenants, enumerate subscriptions, generate KQL, and run queries with consistent scoping.

How to install

Prerequisites: Python 3.10 or newer.

Install the MCP package from the project root.

pip install -e .

Use the wrapper script to run the MCP server and expose it as a stdio MCP server in your client.

chmod +x ./azure-assistant-mcp.sh

Add the MCP server to your client using the wrapper command. Provide the configuration file path and desired scope.

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

Additional configuration and security

Place secrets in azure-config.json and keep it git-ignored. You can point to a custom location via AZURE_ASSISTANT_CONFIG. Ensure you grant the appropriate Reader permissions on the target scopes (subscriptions or management group) for your service principals.

Security best practices include limiting secret exposure, using least privilege for SPNs, and avoiding hard-coded credentials in logs or configs.

Troubleshooting

If you see scope-related errors or limited results, verify your MG scope or subscription list. Use diagnostics mode to inspect how the server resolves scope and which subscriptions are included.

Development

Code resides under the project’s Python source. You can run, customize, and extend the KQL templates used for common Azure queries.

Notes and examples

You can leverage built-in tools to discover tenants, enumerate subscriptions, and execute KQL across ARG with a clearly defined scope.

Available tools

ask-azure

Generates KQL for a natural language question and executes it with appropriate scoping, inferring tenant when possible.

list-tenants

Lists configured tenants with IDs and optional management_group_id and default_subscription_id to help pick scope.

run-arg-kql

Executes a provided KQL query using the determined scope and returns results with header information about Rows, Tenant, and Scope.

run-kql-template

Loads a KQL template, applies parameter substitutions, and runs it with the chosen scope.

list-subscriptions

Enumerates subscriptions, enriched with ARG data, and prefers management group scope when configured.

vm-count-by-tenant

Counts virtual machines per tenant using the defined scoping rules.

diagnostics

Shows configuration resolution details, scope decisions, and sample ARM/ARG results for troubleshooting when debug is enabled.

arg-tables

Presents an overview of ARG tables and their purposes for quick reference.

arg-examples

Provides sample KQL snippets for common scenarios across ARG tables.

Built by

VeilStrat

AI signals for GTM teams