Linuxfabrik Icinga MCP Server

用于 Icinga 的 Model Context Protocol (MCP) server。允许像 Claude 这样的 AI 客户端，通过 Icinga 2 Core、Icinga Web 和 Icinga Director REST API，对 Icinga 安装进行分类、调查和操作，同时深度感知 Linuxfabrik monitoring-plugins 目录以及来自时间序列数据库的历史 perfdata。 • 由 Linuxfabrik 制作

# Icinga MCP Server `mcp-server-icinga` 是一个 Model Context Protocol (MCP) server，它允许像 Claude 这样的 AI 客户端通过自然语言操作 Icinga 安装。它的目标用户是在生产环境中运行 Icinga，并希望在现有的 Icinga REST API 之上，拥有一个用于日常分类、事件调查和常规操作的聊天驱动界面的 Linux 系统工程师。 本项目是在 Anthropic 的 Claude Code 协助下开发的。 ## 范围 该 server 连接了三个 Icinga 表面和 Linuxfabrik monitoring stack： - **Icinga 2 Core REST API** (端口 5665)：实时的 host 和 service 对象、按需检查、确认、停机时间。 - **Icinga Web 2 / Icinga DB Web 模块**：更丰富的状态投影、历史记录、评论、通知，但受到 Icinga Web 表面的限制。 - **Icinga Director API**：对象浏览、service template 内省、命令目录。 - **Linuxfabrik [monitoring-plugins](https://github.com/Linuxfabrik/monitoring-plugins) 目录**：每个 check plugin 的实现、输入、输出、状态和 perfdata，因此 server 不仅能告知 service 正在告警，还能解释原因。 - **时间序列数据库**（默认：InfluxDB，模块化）：用于趋势分析、抖动分析和根因调查的历史 perfdata。 每个 backend 都位于其独立的模块中，以便操作员可以只接入他们实际运行的部分。该 server 会透明地标出底层 API 未公开的信息，而不是进行猜测。 ## 状态 早期开发阶段。架构、配置和工具表面尚不稳定，可能会发生变更。 ## 要求 - Python 3.14 或更高版本。 - 可访问的 Icinga 安装（以下一项或多项：Icinga 2 Core API，带有 Icinga DB Web 模块的 Icinga Web 2，Icinga Director）。 - 可选：用于存储历史 perfdata 的时间序列数据库 backend。默认集成是 InfluxDB；TSDB 层是模块化的，因此可以插入其他 backend。 ## 安装说明 该 server 可以在任何运行 Python 3.14 的地方运行。它不需要部署在 Icinga master 上，但必须能够通过网络访问你指定的 Icinga REST API，并且需要一个支持 MCP 的客户端（已通过 [Claude Desktop](https://claude.ai/download) 和 [Claude Code](https://docs.claude.com/en/docs/claude-code) 测试）。 在第一个 PyPI 版本发布之前，请直接从 GitHub 安装： ``` pip install --user git+https://github.com/Linuxfabrik/mcp-server-icinga.git ``` 对于本地开发，请在虚拟环境中以 editable mode 安装： ``` git clone https://github.com/Linuxfabrik/mcp-server-icinga.git cd mcp-server-icinga python3.14 -m venv .venv source .venv/bin/activate pip install --editable '.' ``` 该 package 同时暴露了一个 console script 和一个可运行的 module： ``` mcp-server-icinga # started by the MCP client over stdio python -m mcp_server_icinga # equivalent ``` 如果没有配置文件，server 将退出并给出明确的错误提示，指出查找顺序。有关完整的操作步骤，请参阅[安装指南](https://linuxfabrik.github.io/mcp-server-icinga/user-guide/02%20-%20Installation/)。 ## 配置 该 server 通过单个 YAML 文件进行配置。它描述了一个或多个 Icinga 部署（“instances”）以及全局的 Linuxfabrik monitoring-plugins 目录。Secrets 不存储在 YAML 中；它们会在加载时从环境变量 (`!env`) 或磁盘上的文件 (`!file`) 中解析。 配置文件的查找顺序如下，匹配到第一个即停止： 1. `ICINGA_MCP_CONFIG` 环境变量中的路径。 2. `$XDG_CONFIG_HOME/Linuxfabrik/mcp-server-icinga/config.yaml`（默认：`~/.config/Linuxfabrik/mcp-server-icinga/config.yaml`）。 3. `/etc/Linuxfabrik/mcp-server-icinga/config.yaml`。 一个具有单个 instance 的最小只读设置： ``` instances: prod: icinga2_core: url: 'https://icinga2.example.com:5665' username: 'mcp-readonly' password: !env ICINGA2_PROD_PASSWORD ``` instance 名称（上例中的 `prod`）是你在聊天中引用的标识符（“`prod` 上目前什么是红色的？”）。每个 instance 最多包含四个独立可选的 backend（`icinga2_core`、`icinga_web`、`icinga_director`、`tsdb`）；如果目标 instance 上不存在工具所需的 backend，则该工具根本不会被注册。包含每个 backend 且带有注释的示例已发布在 [`examples/config.example.yaml`](https://github.com/Linuxfabrik/mcp-server-icinga/blob/main/examples/config.example.yaml) 中。 有关字段参考、secret 处理以及如何将 server 接入 Claude Desktop 或 Claude Code，请参阅[配置指南](https://linuxfabrik.github.io/mcp-server-icinga/user-guide/03%20-%20Configuration/)和[快速入门](https://linuxfabrik.github.io/mcp-server-icinga/user-guide/04%20-%20Quickstart%20with%20Claude/)。 ## 示例提示词 你可以提问的内容取决于你配置了哪些 backend。插件目录可以离线回答问题；实时的 host 和 service 状态需要可访问的 `icinga2_core` instance；确认问题和安排停机时间需要写入凭据。以下是一些入门示例： - “列出所有 Linuxfabrik monitoring plugins，并解释一下 `disk-usage`。” - “`prod-zh` 上目前什么状态不是 OK？” - “为什么 `db01` 上的 `disk` 服务是 critical，而且该检查实际上测量的是什么？” 有关按各自需求分组的完整提示词列表，请参阅[示例提示词指南](https://linuxfabrik.github.io/mcp-server-icinga/user-guide/06%20-%20Example%20Prompts/)。 ## 相关项目 - [Linuxfabrik monitoring-plugins](https://github.com/Linuxfabrik/monitoring-plugins)：该 server 理解的 check plugin 目录。 - [Linuxfabrik lib](https://github.com/Linuxfabrik/lib)：共享的 Python helpers。 - [Icinga/icinga-mcp](https://github.com/Icinga/icinga-mcp)：由 Icinga 团队开发的上游概念验证 MCP server。范围不同，架构也不同。 ## 许可证 根据 [Unlicense](LICENSE) 发布到公共领域。

标签：AI辅助运维, Icinga, MCP, 人工智能交互, 运维监控, 逆向工具