Azure Assistant MCP

🚀 Azure-Assistant-MCP

Azure-Assistant-MCP 是一個輕量級、快速的 MCP 服務器，用於通過 Azure Resource Graph (ARG) 探索 Azure。它可以生成並運行 Kusto 查詢語言 (KQL)，以回答有關 Azure 環境的問題，具有清晰明確的作用域和可選的管理組覆蓋範圍。

🚀 快速開始

本項目允許你直接檢查和運行 ARG KQL，避免了依賴大型組件，提供了一個基於標準輸入輸出的小型 MCP 服務器。

✨ 主要特性

• 自然語言轉 KQL：對於常見任務，可將自然語言轉換為 KQL，並始終顯示查詢內容。
• 直接執行 KQL：直接對 ARG 執行 KQL 查詢，並設置分頁上限（top）。
• 明確的作用域：響應中明確顯示租戶 + 訂閱或管理組的作用域。
• 自動發現訂閱：可自動發現訂閱或在管理組作用域內進行查詢。
• 可選的診斷模式：提供可選的診斷模式，便於快速調試作用域。

📦 安裝指南

安裝依賴

• 從倉庫根目錄執行以下操作：
  • 使用 pip install -e . 進行安裝。
  • 或者使用包裝器腳本：./azure-assistant-mcp.sh（如果存在 .venv，優先使用）。

作為 MCP 標準輸入輸出服務器添加

• 在客戶端中使用包裝器命令將其添加為 MCP 標準輸入輸出服務器。
  • 確保包裝器腳本可執行：chmod +x ./azure-assistant-mcp.sh。
  • 示例（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

💻 使用示例

按管理組列出租戶中的訂閱

• 工具：list-subscriptions
• 輸入：{ "tenant_name": "Contoso" }

統計租戶中所有訂閱的虛擬機數量

• 工具：ask-azure
• 輸入：{ "tenant_name": "Contoso", "question": "How many virtual machines exist?" }

在管理組作用域內直接運行 KQL 查詢所有訂閱

• 工具：run-arg-kql
• 輸入：{ "tenant_name": "Contoso", "kql_query": "resourcecontainers | where type =~ 'microsoft.resources/subscriptions' | project name, subscriptionId | order by name asc" }

📚 詳細文檔

配置

• 將密鑰信息放置在 azure-config.json 文件中（該文件已被 git 忽略）。可參考 azure-config-example.json 的結構。
• 啟動腳本會將 AZURE_ASSISTANT_CONFIG 環境變量指向倉庫中的 azure-config.json 文件，以避免跨倉庫配置衝突。
• 也可以通過設置 AZURE_ASSISTANT_CONFIG 環境變量指向自定義的配置文件位置。

工具使用說明

• ask-azure：輸入 { "question": string, "tenant_name?": string, "subscription_ids?": string[], "use_all_subscriptions?": boolean, "auto_execute?": boolean }，根據問題生成 KQL 查詢。如果 auto_execute 為 true（默認值），則根據作用域規則執行查詢。如果未提供 tenant_name，服務器會從文本中啟發式推斷。
• list-tenants：輸入 {}，列出 azure-config.json 中配置的租戶信息，包括租戶 ID、可選的 management_group_id 和 default_subscription_id，方便選擇作用域和服務主體。
• run-arg-kql：輸入 { "kql_query": string, "tenant_name?": string, "subscription_ids?": string[], "use_all_subscriptions?": boolean, "top?": integer }，根據作用域規則執行提供的 KQL 查詢，並在頭部添加 Rows、Tenant 和作用域信息。
• run-kql-template：輸入 { "template_name": string, "params?": object, "tenant_name?": string, "subscription_ids?": string[], "use_all_subscriptions?": boolean, "top?": integer }，加載 src/azure_assistant_mcp/kql/ 目錄下的模板文件（.md 或 .kql），應用 params 中的參數替換，然後根據作用域規則執行查詢。
• list-subscriptions：輸入 { "tenant_name?": string }，列出訂閱信息。儘可能使用 ARM 枚舉，並使用 ARG 進行補充；如果配置了管理組作用域，則優先使用該作用域以返回完整列表。
• vm-count-by-tenant：輸入 { "tenant_names?": string[], "use_all_subscriptions?": boolean }，根據作用域規則統計每個租戶的虛擬機數量。
• diagnostics（僅當 debug 為 true 時顯示）：輸入 { "tenant_name?": string }，打印配置文件路徑、解析的租戶、規範化的管理組 ID、ARM 枚舉示例和數量、ARG 管理組覆蓋示例和數量以及默認作用域決策。
• arg-tables：輸入 {}，打印常見 Azure Resource Graph 表（resourcecontainers、resources、resourcechanges、advisorresources、healthresources、policyresources）的概述，包括用途和典型用例。
• arg-examples：輸入 { "topic?": string }，其中 topic 可以是 subscriptions、resourcegroups、changes、containerchanges、advisor、health 或 policy，返回 ARG 表中常見場景的示例 KQL 代碼片段。

KQL 模板（自定義查詢）

• 可以在不修改 Python 代碼的情況下編輯內置工具和示例使用的 KQL 查詢。
• 模板文件存放在 src/azure_assistant_mcp/kql/ 目錄下，以 .md 文件（包含 fenced ```kql 塊）或 .kql 文件的形式存在。
• 運行時，服務器會加載這些模板文件。如果缺少必需的模板文件，服務器會拋出錯誤，以便你進行修復。
• 可以通過設置 AZURE_ASSISTANT_KQL_PATH 環境變量將模板目錄替換為其他目錄。
• 示例模板文件：
  • 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
  • 你可以創建自己的模板文件，例如 kubernetes_inventory.md，然後使用 run-kql-template { "template_name": "kubernetes_inventory", "params": { ... } } 運行。

🔧 技術細節

作用域規則

• 如果提供了 subscription_ids，則使用這些訂閱。
• 否則，如果 use_all_subscriptions 為 true 且配置了 management_group_id，則在 ARG 中以管理組作用域運行查詢。
• 否則，嘗試通過 ARM 枚舉訂閱並使用該列表。
• 否則，回退到 default_subscription_id。
• 響應中始終會打印 Tenant 信息以及 Scope: managementGroup=... 或 Subscriptions used: N。

開發信息

• 代碼存放在 src/azure_assistant_mcp/ 目錄下，入口點為 azure_assistant_mcp:main。
• 包裝器腳本為 azure-assistant-mcp.sh（設置 PYTHONPATH 環境變量並固定 AZURE_ASSISTANT_CONFIG 環境變量）。
• 向後兼容的別名腳本 azure-assistant.sh 已棄用。
• 依賴項包括 mcp、python-dotenv、azure-identity、azure-mgmt-resourcegraph、azure-mgmt-subscription。

📄 許可證

本項目採用 Apache-2.0 許可證。完整的許可條款請參閱 LICENSE 文件。根據 Apache-2.0 許可證第 4(d) 條，再分發者必須在任何源代碼分發以及通常顯示此類通知的文檔或關於對話框中保留 NOTICE 文件中的歸屬聲明。

⚠️ 重要提示

• 請自行承擔使用本項目的風險。本項目按“原樣”提供，不提供任何形式的保證或擔保。你對其使用方式負全部責任，包括配置、訪問控制以及遵守組織的政策。作者和貢獻者不對因使用本軟件而導致的任何損害、數據丟失、安全事件、成本或政策違規負責。不暗示任何僱主或組織對本項目的認可或支持。
• 不要提交真實的憑據信息。azure-config.json 文件已被 git 忽略，請使用示例文件作為模板。
• 請確保服務主體在查詢的作用域內具有最小權限。

💡 使用建議

• 企業用戶可在文檔或關於頁面中對本項目進行歸屬聲明。
• 如果你的組織從本項目中受益，請考慮進行贊助或簽訂商業支持協議。如有商業支持/許可方面的諮詢，請創建一個 issue 或聯繫維護者。也可通過 Buy Me A Coffee 進行支持。

🔗 相關鏈接

• 建議的子代理：Claude_Agents/azure-cloud-architect.md，這是一個 Azure 雲架構助手，你可以在 Claude Code 中與本 MCP 服務器一起加載使用。開始使用時，將 Claude_Agents/azure-cloud-architect.md 文件複製到 .claude/agents 文件夾中。

👥 貢獻

歡迎提交問題和拉取請求。請在示例和日誌中避免包含真實的租戶 ID、密鑰或組織名稱。