icinga-mcp

MCP/MCPO and REST bridge for Icinga Web 2 (Icinga DB Web module).

Important: This repository is not an officially supported Icinga product. It is a proof of concept aimed at learning about usage profiles and requirements. Use for experiments and lab environments; production use is at your own risk. Feedback is welcome via issues and PRs.

Table of contents

• Features
• How it works
• Prerequisites
• Quickstart
• Configuration
• REST API
• MCP tools (MCPO)
• Container (Docker/Podman)
• Development
• License
• Feedback and support
• Links

Features

icinga-mcp exposes two surfaces:

• FastAPI REST server with auto-generated OpenAPI/Swagger UI.
• MCP server implementing the Model Context Protocol (MCP) so MCPO can call monitoring actions as tools.

Capabilities:

• Talks to Icinga Web 2: Icinga DB Web module (not the Icinga 2 core API).
• Read/write operations: list hosts/services/problems, groups, history; comments; acknowledgements; downtimes; notifications; on-demand checks.
• Optional normalization/summary projections for UI/LLM consumption.

References: src/icinga_mcp/rest_app.py, src/icinga_mcp/services.py, docs/icinga-web-api.md.

How it works

• MCP: stdio server speaking the MCP protocol so MCPO can use tools like list_hosts, schedule_downtime, acknowledge, etc.
• REST/OpenAPI: HTTP facade with documented schema and Swagger UI; forwards to Icinga DB Web endpoints and applies optional projections.
• Both surfaces use the same service layer and upstream mapping.

Prerequisites

• Python 3.11 or newer (3.12 also works).
• Icinga Web 2 with the Icinga DB Web module reachable via HTTP/HTTPS.
• Network connectivity from this service to Icinga Web 2.

Quickstart

The steps below describe a typical local setup using a Python virtual environment. For a container-based workflow, see Container (Docker/Podman).

1. Create and activate a virtualenv, then install dependencies

make venv
. .venv/bin/activate
make dev  # installs the package in editable mode plus dev/test tooling and pre-commit hooks

2. Copy and edit environment configuration

cp .env.example .env
# Required upstream settings:
#   ICINGA_WEB_BASE_URL=https://icingaweb2.example.tld
#   ICINGA_WEB_USERNAME=...
#   ICINGA_WEB_PASSWORD=...
# TLS options:
#   ICINGA_WEB_VERIFY_TLS=true        # default: true
#   ICINGA_WEB_CA_BUNDLE=/path/to/ca.pem
# REST auth (optional but recommended):
#   REST_REQUIRE_API_KEY=true
#   REST_BEARER_TOKEN=super-secret
# REST bind:
#   REST_HOST=127.0.0.1
#   REST_PORT=8080

3. Run the REST server

make run-rest
# or, after `pip install -e .`:
icinga-mcp-rest

Swagger UI: http://127.0.0.1:8080/docs

4. Verify the REST API health

icinga-mcp-health

5. (Optional) Run the MCP server for MCPO

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

See docs/mcpo-setup.md and helpers in scripts/.

Configuration

Environment variables live in .env; an example is in .env.example. Key options:

• ICINGA_WEB_BASE_URL, ICINGA_WEB_USERNAME, ICINGA_WEB_PASSWORD
• ICINGA_WEB_VERIFY_TLS, ICINGA_WEB_CA_BUNDLE
• REST_REQUIRE_API_KEY, REST_BEARER_TOKEN
• REST_HOST, REST_PORT

Secrets are never logged; TLS verification is on by default. Use a least-privilege Icinga Web 2 account.

REST API

• OpenAPI/Swagger: GET /docs and /openapi.json while the REST server is running.
• Authentication (optional but recommended): set REST_REQUIRE_API_KEY=true and REST_BEARER_TOKEN, then call endpoints with: Authorization: Bearer
• Endpoint families (high level):
  • Hosts and services: list, problems, history
  • Groups: hostgroups, servicegroups (overview and single-group detail)
  • Downtimes: list, schedule host/service, remove by composite name
  • Comments: list, add host/service, remove by composite name
  • Acknowledgements: add/remove for host/service
  • Notifications: enable/disable host/service; list notifications
  • Search: cross-object name lookup across hosts, services, hostgroups and servicegroups
  • Checks: reschedule host/service, process check results
• Filtering and pagination:
  • Use dotted filters like host.name or service.name; convenience params host and service are mapped for you
  • Summary and fields parameters can return compact normalized shapes

Complete, up-to-date route and parameter notes: docs/icinga-web-api.md. Example requests: examples/http-examples.http.

Quick examples

# List services with problems (requires Bearer if enabled)
curl -H "Authorization: Bearer $REST_BEARER_TOKEN" \
  'http://127.0.0.1:8080/problems/services?page=1&limit=50&host=web01'

# Schedule a 1-hour host downtime
curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer $REST_BEARER_TOKEN" \
  'http://127.0.0.1:8080/downtime/host?host=web01' \
  -d '{"comment":"maintenance","window":"hour"}'

# Add a service comment
curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer $REST_BEARER_TOKEN" \
  'http://127.0.0.1:8080/comment/service?service=HTTP&host=web01' \
  -d '{"comment":"Investigating"}'

# Search across hosts, services and groups by name
curl -H "Authorization: Bearer $REST_BEARER_TOKEN" \
  'http://127.0.0.1:8080/search?name=vm'

Notifications (example)

# List notifications (summary) for a host with explicit fields
curl -H "Authorization: Bearer $REST_BEARER_TOKEN" \
  'http://127.0.0.1:8080/notifications?host=web01&fields=time,host,service,author,text'

Target Web URL

export ICINGA_WEB_BASE_URL="https://monitoring.example.com/icingaweb2"

MCP tools (MCPO)

• Exposes tools analogous to core REST operations for MCPO orchestration (list_hosts, list_services, list_host_problems, list_service_problems, history, comments, downtimes, groups, etc.).
• Start the server with make run-mcp or the icinga-mcp-server console script, then configure MCPO to spawn/connect.
• MCPO setup and usage examples: docs/mcpo-setup.md.

Container (Docker/Podman)

A ready-to-build container is provided via the root-level Containerfile. It runs the REST server by default, loads your .env, and exposes port 8080. This section mirrors the local Quickstart, but for Docker/Podman users.

Prerequisites

• Docker or Podman installed
• Copy and edit environment: cp .env.example .env

Build the image

# Docker
docker build -t icinga-mcp:local -f Containerfile .

# Podman
podman build -t icinga-mcp:local -f Containerfile .

Run the REST API (port-forward + .env)

docker run --rm --name icinga-mcp \
  -p 8080:8080 \
  --env-file ./.env \
  icinga-mcp:local

# Alternative: bind-mount .env into /app/.env (read-only)
docker run --rm --name icinga-mcp \
  -p 8080:8080 \
  -v "$PWD/.env":/app/.env:ro \
  icinga-mcp:local

Verify the service

# If REST auth is disabled
curl -fsS http://localhost:8080/health

# If REST auth is enabled
curl -fsS -H "Authorization: Bearer $REST_BEARER_TOKEN" http://localhost:8080/health

Swagger UI: http://localhost:8080/docs

TLS CA bundle (optional)

docker run --rm --name icinga-mcp \
  -p 8080:8080 \
  --env-file ./.env \
  -v "$PWD/ca.pem":/app/ca.pem:ro \
  -e ICINGA_WEB_CA_BUNDLE=/app/ca.pem \
  icinga-mcp:local

Run the MCP stdio server (instead of REST)

docker run --rm --name icinga-mcp-stdio \
  --env-file ./.env \
  --entrypoint icinga-mcp-server \
  icinga-mcp:local

Notes

• In the container, REST_HOST defaults to 0.0.0.0; no change required for port mapping.
• Container EXPOSEs 8080; publish with -p 8080:8080 (or any host port you prefer).
• Healthcheck inside the image calls /health and uses REST_BEARER_TOKEN if set.
• The image runs as a non-root user (UID 10001); ensure mounted files (e.g., .env, CA bundle) are readable by that UID).

Development

Common make targets (see Makefile):

• venv: create .venv (override with PYTHON=python3.12)
• install: editable install of the package into the venv
• dev: install dev deps and pre-commit hooks
• fmt: black + ruff --fix on src and tests
• lint: ruff check
• type: mypy type-check
• test: pytest
• run-rest: launch uvicorn with reload
• run-mcp: launch the stdio MCP server
• ci: run the usual local CI chain

Testing and CI

• Unit tests live under tests/ (currently focused on filters, the HTTP client and the service layer).
• Install test/dev dependencies with either make dev or pip install -e ".[dev]". This pulls in pytest, pytest-asyncio and the other tools used by the test suite and CI.
• Run pytest locally (or make test) to execute the test suite.
• The CI workflow at .github/workflows/ci.yml runs on every push and pull request to main and executes:
  • editable install with dev dependencies (pip install -e ".[dev]")
  • linting via ruff and formatting check via black
  • type checking via mypy on src/
  • the same pytest suite you can run locally

Keeping local make ci green should match what GitHub Actions enforces.

License

Licensed under GPL v2 (SPDX: GPL-2.0-only). See LICENSE and https://www.gnu.org/licenses/old-licenses/gpl-2.0.txt

Feedback and support

This is experimental software and not supported by Icinga as a product. Issues and PRs are welcome to help shape future direction and capture real-world requirements.

Links

• REST details and endpoint behavior: docs/icinga-web-api.md
• MCPO setup and tool usage: docs/mcpo-setup.md
• Example requests: examples/http-examples.http
• REST app: src/icinga_mcp/rest_app.py
• Service layer: src/icinga_mcp/services.py