icinga-mcp

MCP server for analysing an Icinga 2 monitoring setup with an LLM. Implements the Model Context Protocol revision 2026-07-28 (via the official Python SDK, which also falls back to 2025-11-25 for older clients).

Status: early development. Available on PyPI.

Scope (v1)

• Read active problems, host/service details, comments and downtimes (Icinga 2 REST API)
• Acknowledge problems, add comments, schedule/remove downtimes (opt-in, every change is confirmed by the user)
• Tools are grouped into toolsets that can be enabled/disabled individually; read-only by default
• Alert history via the IcingaDB Web module, optional (legacy monitoring module supported)
• Icinga Director configuration (read-only): hosts, templates, apply rules, commands, optional

Runs on Linux, macOS and Windows (Python 3.11+).

Creating, changing or deleting monitoring objects is intentionally out of scope.

Installation

icinga-mcp is started by your MCP client via uv. Install uv once:

# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Quick start (VS Code)

Add the server to your MCP configuration. Recommended: the user configuration (command palette: MCP: Open User Configuration), so the credentials stay outside of any repository. A workspace file .vscode/mcp.json works too, but must not be committed.

{
  "servers": {
    "icinga": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "domon-mcp-server", "icinga-mcp"],
      "env": {
        "ICINGA_URL": "https://icinga-master.example.com:5665",
        "ICINGA_USER": "icinga-mcp",
        "ICINGA_PASSWORD": "change-me",
        "ICINGAWEB_URL": "https://icinga.example.com",
        "ICINGAWEB_USER": "jdoe",
        "ICINGAWEB_PASSWORD": "change-me",
        "ICINGA_MCP_READ_ONLY": "false",
        "ICINGA_MCP_AUTHOR": "jdoe"
      }
    }
  }
}

The ICINGAWEB_* lines enable the alert history and the Director tools (optional). Omit the last two lines to keep icinga-mcp read-only. The password is stored in plain text in this file. Use a dedicated, minimally privileged ApiUser (see permissions) and protect the file accordingly.

To run from a local checkout instead of PyPI:

      "command": "uv",
      "args": ["run", "--directory", "/path/to/icinga-mcp", "icinga-mcp"],

On Windows use forward slashes or escaped backslashes in JSON paths, e.g. "C:/Users/me/icinga-mcp".

Configuration

All settings are read from environment variables (the env block of the MCP configuration).

Icinga Web: history and Director (optional)

The Icinga 2 API has no history and does not know the Director data model. get_history reads alert history from Icinga Web 2's IcingaDB module by default, the director_* tools read the configuration from the Icinga Director REST API. Both are only available when these variables are set:

TLS certificate verification (optional)

Icinga 2 API certificates are usually signed by the internal Icinga CA, which no operating system trusts. By default icinga-mcp therefore connects without certificate verification and logs a warning. The API password is still sent encrypted, but the server identity is not checked, so a man-in-the-middle could capture the credentials.

To enable verification, store the CA once per instance and add to the env block:

        "ICINGA_CA_CERT": "/home/me/.config/icinga-mcp/<instance>-ca.pem",
        "ICINGA_TLS_SERVER_NAME": "<CN of the server certificate>"

ICINGA_TLS_SERVER_NAME is only needed if the certificate name differs from the URL host. The CA is the last certificate printed by the following command (OpenSSL is included in Linux, macOS and Git for Windows):

openssl s_client -connect <host>:5665 -showcerts </dev/null

Compare the CA fingerprint (openssl x509 -in <file> -noout -fingerprint -sha256) with the one provided by your Icinga administrators.

Icinga 2 API permissions

Minimal ApiUser permissions:

object ApiUser "icinga-mcp" {
  password = "..."
  permissions = [
    "status/query",
    "objects/query/Host", "objects/query/Service",
    "objects/query/HostGroup", "objects/query/ServiceGroup",
    "objects/query/Comment", "objects/query/Downtime",
    // only needed for write tools
    "actions/acknowledge-problem", "actions/remove-acknowledgement",
    "actions/add-comment", "actions/schedule-downtime", "actions/remove-downtime",
  ]
}

Tools

Values below keys whose names look sensitive (*pass*, *secret*, *token*, *basicauth*, ...) are replaced by ***REDACTED*** in all tool results. Pure macro references such as $snmp_password$ (e.g. in command arguments) stay visible because they contain no secret.

Enabling and disabling tools

Disabled tools are not registered at all, so the model never sees them. icinga-mcp list-tools shows the effective selection.

Write tools and safety

Write tools are only available with ICINGA_MCP_READ_ONLY=false and need these settings:

Safety measures:

• Targets are exact object names (host or host!service), never patterns or free filters. All targets are looked up first; unknown names abort the call before anything is changed.
• Every change is confirmed by the user. If the MCP client supports elicitation (e.g. VS Code), the user gets a dialog listing the objects and options. Clients without elicitation get a preview on the first call; only a second call with confirm=true applies the change. In that mode the model is instructed to ask the user first, but technically it could set confirm=true on its own; set ICINGA_MCP_REQUIRE_ELICITATION=true to rule that out.
• Results report per object whether Icinga applied the change.

Command line

check reads the same environment variables as the server:

# Linux / macOS
ICINGA_URL=https://icinga-master:5665 ICINGA_USER=icinga-mcp ICINGA_PASSWORD='...' uvx --from domon-mcp-server icinga-mcp check

# Windows (PowerShell)
$env:ICINGA_URL = "https://icinga-master:5665"; $env:ICINGA_USER = "icinga-mcp"; $env:ICINGA_PASSWORD = "..."
uvx --from domon-mcp-server icinga-mcp check

Development

uv sync
uv run pytest                    # unit tests
uv run pytest -m integration     # read-only tests against a real instance (needs ICINGA_* env)
uv run ruff check .
uv run ruff format --check .
uv run mypy

See AGENTS.md for architecture and conventions.