Azure Assistant MCP

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): ```bash 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. - [](https://www.buymeacoffee.com/iOSDevil)