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、密钥或组织名称。