home / mcp / azure assistant mcp server

Azure Assistant MCP Server

Provides a minimal MCP server to explore Azure ARG by translating natural language to KQL and executing queries with explicit scope.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "andrewstephenson-v1-azure-assistant-mcp": {
      "command": "./azure-assistant-mcp.sh",
      "args": [],
      "env": {
        "AZURE_ASSISTANT_CONFIG": "/path/to/azure-config.json"
      }
    }
  }
}

Azure-Assistant-MCP is a minimal, fast MCP server that uses Azure Resource Graph (ARG) to answer questions about your Azure environment. It translates natural language requests into KQL queries, runs them with explicit scoping (tenant + subscriptions or management group), and returns results with clear context and paging controls. This setup is ideal for quick exploration of ARG without heavy dependencies.

How to use

You interact with the MCP server through an MCP client. The server exposes tools that let you generate KQL from natural language questions, run ARG queries at a defined scope, and inspect common ARG tables. You can list configured tenants, enumerate subscriptions, run KQL directly, or use templates to load prebuilt queries. Every response includes the Tenant and the effective scope (managementGroup=... or Subscriptions used: N) so you know exactly where the data came from.

Key workflows you can perform include: generating a KQL query from a natural-language question, executing a query across a subset of subscriptions or at management-group scope, and reviewing sample KQL templates for common Azure resource queries. Use the provided tools to manage scope and observe how ARG results are paged with top-based limits.

How to install

Prerequisites you need before installing: Python 3.10 or newer and Azure Service Principals with Reader access at your target scope.

Install steps from the project root:

pip install -e .
```

You can also use the wrapper to run the MCP server if a virtual environment is present:

./azure-assistant-mcp.sh
```

Make sure the wrapper is executable before using it:

Add the MCP server to your MCP client using the wrapper command. For example, in Claude Desktop CLI you would run:

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

Store secrets in a JSON file named azure-config.json. This file is ignored by version control. You can find a structure example file azure-config-example.json to guide you.

The launch wrapper exports AZURE_ASSISTANT_CONFIG to azure-config.json to avoid cross-repo configurations. You can point the server to a custom location by settingAZURE_ASSISTANT_CONFIG to your path.

Configuration details and scope rules

The server supports multiple scoping options to determine where KQL runs: it uses explicit subscriptions if provided, or MG scope if configured to query at a management group, or enumerates subscriptions via ARM when possible. The resulting responses always show the Tenant and the chosen scope.

Available tools and usage patterns

Tools include generation and execution of KQL from natural language, listing tenants, running ARG queries, using KQL templates, listing subscriptions, counting resources (e.g., VMs) per tenant, diagnostics for scope debugging, and ARG table overviews.

Security

Do not commit real credentials. azure-config.json is git-ignored; use a template for structure. Consider storing secrets securely and limiting service principals to the least privileges required for the scopes you query.

Troubleshooting

If you see only one subscription, provide a broader scope by adding a management group that contains all targets or specify subscription_ids directly. If ARG returns BadRequest, verify the KQL syntax and the selected scope. For quick scope validation, enable diagnostics and run the diagnostics tool for the tenant.

Development

Code lives under src/azure_assistant_mcp/. Entry point is azure_assistant_mcp:main. The wrapper script is azure-assistant-mcp.sh, which sets PYTHONPATH and the AZURE_ASSISTANT_CONFIG environment variable. A backwards-compatible alias azure-assistant.sh exists but is deprecated.

Usage examples

List subscriptions for a tenant by MG using list-subscriptions. Count VMs across all subs using ask-azure with a question. Run KQL directly across all subs at MG scope using run-arg-kql.

Notes

The MCP server requires Python 3.10+, and Azure SPNs must have Reader access at the intended scope. The server ships with a small, stdio-based MCP server for exploring ARG and generates KQL automatically.

Arg and templates overview

You can browse common ARG tables like resourcecontainers, resources, resourcechanges, and others, and use templates to load predefined KQL blocks. Templates live in src/azure_assistant_mcp/kql/ and can be overridden by setting AZURE_ASSISTANT_KQL_PATH.

Available tools

ask-azure

Generates a KQL query from a natural-language question and, if auto_execute is true, executes it using the defined scoping rules.

list-tenants

Lists configured tenants from azure-config.json with their IDs and optional management_group_id and default_subscription_id.

run-arg-kql

Executes a provided KQL query using the Scoping Rules and returns Rows with Tenant and scope header.

run-kql-template

Loads a KQL template, applies parameter substitutions, and executes it using the Scoping Rules.

list-subscriptions

Lists Azure subscriptions for a given tenant, enriched with ARG scope information when possible.

vm-count-by-tenant

Counts virtual machines per tenant using the Scoping Rules.

diagnostics

Prints detailed configuration and scope debugging information when debug mode is enabled.

arg-tables

Prints an overview of common ARG tables and their purposes.

arg-examples

Provides sample KQL snippets for common ARG scenarios across tables.