AI导哈

Azure资源查询服务器

一个轻量级的MCP服务器，用于通过Azure Resource Graph (ARG) 生成和执行KQL查询，以探索和分析Azure环境。

  • by iOSDevil
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 iosdevil/azure-assistant-mcp

使用说明

Azure助理MCP

使用Azure资源图（ARG）探索Azure的最小、快速的MCP服务器。它生成并运行KQL来回答有关Azure环境的问题，具有清晰、明确的范围和可选的管理组覆盖范围。

免责声明

使用此项目的风险由您自行承担。它“按原样”提供，不提供任何形式的保证或担保。您全权负责如何使用它，包括配置、访问控制和遵守组织的策略。作者和贡献者对使用本软件造成的任何损害、数据丢失、安全事件、费用或违反政策不承担责任。没有雇主或组织暗示支持或支持这个项目。

为什么存在

  • 使直接检查和运行ARG KQL变得简单。
  • 避免重量级依赖；运送一个基于stdio的小型MCP服务器。

亮点

  • 自然语言→ KQL用于常见任务；始终显示查询。
  • 使用分页上限直接对ARG执行KQL(top).
  • 响应中的显式范围：租户+订阅或管理组。
  • 在管理组范围内自动发现订阅或查询。
  • 用于快速范围调试的可选诊断模式。

需求

  • Python 3.10+
  • Azure SPN 读者 在您想要查询的范围内：
    • 订阅： 读者 在每个目标订阅上
    • 管理组： 读者 关于MG（和基础资源）

安装

  • 从repo根目录：
    • pip install -e .
    • 或者使用包装器： ./azure-assistant-mcp.sh （更喜欢 .venv 如果存在）
  • 使用包装器命令在客户端中添加为MCP stdio服务器。

    • 确保包装器可执行： chmod +x ./azure-assistant-mcp.sh

    • 示例（Claude桌面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

配置

  • 把你的秘密放进去 azure-config.json （被git忽略）。看 azure-config-example.json 对于结构。
  • 启动脚本导出 AZURE_ASSISTANT_CONFIG 到回购 azure-config.json 以避免意外的交叉回购配置。
  • 您还可以通过以下方式指向自定义位置 AZURE_ASSISTANT_CONFIG.

模式

  • 最高级
    • debug （可选）：启用诊断工具
    • tenants：已配置租户列表
  • 每位租户
    • id：租户guid
    • name：友好名称
    • service_principal.client_id / service_principal.client_secret
    • default_subscription_id （可选回退）
    • management_group_id （可选；短名称如 contoso-root 或完整资源id）。服务器将标准化为短名称。

范围规则

  • 如果 subscription_ids 提供：使用这些订阅。
  • 否则，如果 use_all_subscriptions 这是真的 management_group_id 已配置：在ARG的MG范围内运行。
  • 否则，尝试通过ARM枚举订阅并使用该列表。
  • 否则，请返回 default_subscription_id.
  • 响应始终打印 Tenant 并且要么 Scope: managementGroup=... 或 Subscriptions used: N.

工具

  • 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 以帮助您选择范围和SPN。

  • 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/<template_name>.md （带围栏的kql）或 .kql，应用简单 {{key}} 替换自 params，并按照范围界定规则执行。

  • list-subscriptions:

    • 输入： { "tenant_name?": string }
    • 列出订阅。尽可能使用ARM枚举，用ARG丰富；如果配置为返回完整列表，则更喜欢MG作用域。

  • vm-count-by-tenant:

    • 输入： { "tenant_names?": string[], "use_all_subscriptions?": boolean }
    • 使用范围界定规则对每个租户运行一个简单的VM计数。

  • diagnostics （仅在以下情况下显示 debug 是真的）：

    • 输入： { "tenant_name?": string }
    • 打印配置路径、解析的租户、标准化的MG id、ARM枚举样本和计数、ARG MG覆盖率样本和计数以及默认范围决定。

  • arg-tables:

    • 输入： {}
    • 打印常见Azure资源图表（资源容器、资源、资源更改、建议资源、健康资源、策略资源）的概述，包括目的和典型用例。

  • arg-examples:

    • 输入： { "topic?": string } 主题可以在哪里 subscriptions, resourcegroups, changes, containerchanges, advisor, health，或 policy.
    • 返回ARG表中常见场景的示例KQL代码段。

KQL模板（自定义查询）

  • 您可以编辑内置工具和示例使用的KQL，而无需接触Python代码。
  • 模板位于 src/azure_assistant_mcp/kql/ 作为 .md 带有带围栏的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": { ... } }.

使用示例

  • 按MG列出租户中的订阅：
    • 工具： list-subscriptions
    • 输入： { "tenant_name": "Contoso" }
  • 统计租户中所有子服务器的虚拟机数量：
    • 工具： ask-azure
    • 输入： { "tenant_name": "Contoso", "question": "How many virtual machines exist?" }
  • 直接在MG范围内的所有子系统上运行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忽略；使用示例文件作为模板。
  • 考虑将机密存储在安全存储中，并对配置进行模板化。
  • 确保服务主体对您查询的范围具有最低权限。

故障排除

  • 只看到一个订阅：
    • 添加a management_group_id 包含所有目标订阅或传递 subscription_ids 明确地。
  • BadRequest 来自ARG：
    • 检查KQL语法和所选范围。从开始 run-arg-kql 使用一个小查询和 top.
  • 快速验证范围：
    • 启用 debug: true 并运行 diagnostics 租户的工具。

发展

  • 代码存在于 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.

克劳德代码

  • 建议的分代理： Claude_Agents/azure-cloud-architect.md --一个Azure云架构助手，您可以在Claude Code中与此MCP服务器一起加载。
  • 开始：
    • 复制 Claude_Agents/azure-cloud-architect.md 进入你的 .claude/agents 文件夹

贡献

  • 欢迎发布问题和PR。请在示例和日志中省略真实的租户ID、机密或组织名称。

许可证

  • 根据Apache-2.0许可。看 LICENSE 完整条款。
  • 归因：该项目包括 NOTICE 文件。根据Apache-2.0§4（d），再分发者必须在 NOTICE 在任何源代码发行版、文档或通常出现此类通知的对话框中。

商业用途和赞助

  • 鼓励企业用户在文档或相关页面中对项目进行归因。
  • 如果您的组织从该项目中受益，请考虑赞助或商业支持协议。
  • 选项：
    • 商业支持/许可证查询：打开问题或联系维护人员。

相关 MCP