icinga

icinga-mcp provides two surfaces: a REST API (FastAPI) with an auto-generated OpenAPI/Swagger UI and an MCP stdio server that speaks the MCP protocol so MCPO can orchestrate monitoring actions. The REST layer acts as a bridge to Icinga Web 2 (Icinga DB Web module) and exposes endpoints to list and manipulate hosts, services, groups, downtimes, comments, acknowledgements, and more, with optional projection for UI or LLM consumption. The MCP server mirrors these capabilities through OCPO-like tools such as list_hosts, list_services, list_host_problems, schedule_downtime, acknowledge, and others, enabling MCPO to orchestrate checks, downtimes, and administrative actions programmatically. To run locally, you typically start the REST API first, then the MCP server for MCPO to connect, and configure MCPO to spawn/connect to the MCP surface.

Prerequisites:

• Python 3.11+ (3.12 also works)
• Access to an Icinga Web 2 instance with the Icinga DB Web module
• Network connectivity from this service to Icinga Web 2

Step-by-step installation:

# 1) Create and activate a Python virtual environment
make venv
. .venv/bin/activate

# 2) Install the package in editable mode along with dev tooling
make dev

Configure environment (example):

cp .env.example .env
# Edit .env with your values for ICINGA_WEB_BASE_URL, ICINGA_WEB_USERNAME, ICINGA_WEB_PASSWORD, and optional TLS/REST settings

Run REST server (local):

make run-rest
# alternatively, if installed as a package in editable mode:
icinga-mcp-rest

Run MCP server for MCPO:

make run-mcp
# or:
icinga-mcp-server

For containerized usage, see the Containerfile in the repo and build/run as described in the Container (Docker/Podman) section of the README.

Tips and notes:

• Secrets are not logged; TLS verification is enabled by default. Use a least-privilege Icinga Web 2 account.
• The MCP surface supports commands like list_hosts, list_services, list_host_problems, and downtime-related actions. MCPO can spawn/connect to the MCP server to orchestrate these actions.
• If REST authentication is enabled, authorize requests with a Bearer token.
• Ensure ICINGA_WEB_BASE_URL is reachable from the MCP REST layer and that the Icinga DB Web module is exposed over HTTP/HTTPS as configured.
• When running in Docker/Podman, mount your .env into the container or rely on a properly passed environment file; see the container docs for TLS and CA bundle options.