openITCOCKPIT MCP Server

An MCP server that exposes an openITCOCKPIT monitoring instance to an LLM client: host and service status, log entries, downtimes, acknowledgements, check history, software inventory and pending updates - plus optional, off-by-default tools that change the monitoring configuration.

• Requires openITCOCKPIT 5.6 or newer. See Compatibility.

• 39 tools, 24 read-only and 15 write.

• Write tools are disabled by default and are not even registered until you enable them.

• Names, never IDs. Every tool takes hostnames, template names and container paths; the server resolves them itself.

• Scope-checked writes. References are validated against the target container before anything is sent, which openITCOCKPIT's own API does not do.

Quickstart

cp .env.example .env          # fill in the two secrets, see Configuration
docker compose up --build

Then point your client at http://localhost:8000/mcp with the bearer token from your .env. Compose reads that same file for the published port, so setting OITC_PORT there moves both sides at once.

Configuration

The server needs two separate secrets and refuses to start if they are the same value:

python -c "import secrets; print(secrets.token_urlsafe(32))"   # generate MCP_AUTH_TOKEN

Copy .env.example to .env and fill it in. Precedence, highest first: CLI flags → environment variables → .env → defaults. .env is gitignored and must never be committed.

Connecting a client

HTTP (server runs as a service)

Clients send Authorization: Bearer <MCP_AUTH_TOKEN>. The comparison is constant-time; a missing, malformed or wrong token gets HTTP 401.

{
  "url": "http://your-mcp-server:8000/mcp",
  "headers": { "Authorization": "Bearer your-mcp-auth-token" }
}

stdio (client spawns the server)

No HTTP layer, so no MCP_AUTH_TOKEN is needed. Two ways to spawn it.

From the image, which needs nothing installed but Docker. This is what the MCP Registry entry describes, and the form to hand to someone who just wants to connect a desktop client:

{
  "command": "docker",
  "args": [
    "run", "-i", "--rm",
    "-e", "OITC_TRANSPORT=stdio",
    "-e", "OITC_APIKEY",
    "-e", "OITC_BASEURL",
    "openitcockpit/mcp-server:0.2.0"
  ],
  "env": {
    "OITC_APIKEY": "your-openitcockpit-api-key",
    "OITC_BASEURL": "https://openitcockpit.example.org"
  }
}

The -e NAME flags carry no value: Docker takes it from the environment the client provides, so neither secret ends up in the process list.

From an install, once pip install . has put oitc-mcp on the path:

{
  "command": "oitc-mcp",
  "args": ["--transport", "stdio"],
  "env": {
    "OITC_APIKEY": "your-openitcockpit-api-key",
    "OITC_BASEURL": "https://openitcockpit.example.org"
  }
}

Installation

Docker

docker run -d -p 8000:8000 --env-file .env openitcockpit/mcp-server:0.2.0

Which tag? The tag is this server's own version. 0.2.0 never changes, so a redeploy gives you exactly what you tested - pin that. latest is the only other tag and it moves under you. The tag says nothing about your openITCOCKPIT version; one image serves 5.6 and newer. See Versioning.

Or with individual variables, for CI or a secret manager:

docker run -d -p 8000:8000 \
  -e MCP_AUTH_TOKEN="..." \
  -e OITC_APIKEY="..." \
  -e OITC_BASEURL="https://openitcockpit.example.org" \
  openitcockpit/mcp-server:0.2.0

No secret is baked into the image; configuration is read from the environment at start-up.

Or with Compose. docker-compose.example.yml is a complete deployment of the published image - restart policy, health check, and every setting inline in two blocks, required and optional. Copy it, fill in the three required values, and:

docker compose -f docker-compose.example.yml up -d

The docker-compose.yml next to it is a different thing: it builds from this repository and reads .env, which is what Quickstart uses.

From source

pip install .
cp .env.example .env
oitc-mcp

oitc-mcp --help lists the flags that override the configuration (--transport, --host, --port, --log-level).

MCP Registry

server.json in the repo root is this server's entry for the MCP Registry, published with mcp-publisher publish. The registry name is io.github.openITCOCKPIT/mcp-server, and the Dockerfile carries the same string as an io.modelcontextprotocol.server.name label - the registry reads it off the published image as its only ownership proof for an OCI package, and compares it case-sensitively.

Three values have to agree at release time: MCP_VERSION, the version in server.json, and the image tag in its package identifier. tests/test_server_json.py fails when they do not.

Tools

39 tools, 24 read-only and 15 write. Full signatures and behaviour: read tools · write tools.

Every tool carries MCP annotations, so a client can tell a read from a write before calling it, and takes names rather than database IDs - the server resolves them itself.

A few things you can ask for, and what answers them:

Write tools are registered only when OITC_ENABLE_WRITE_TOOLS=true. They change your monitoring configuration.

docs/openitcockpit-api-notes.md documents the API behaviour this server works around - which endpoints omit newly created objects, the two names a service template carries, and the response shapes.

Skills

src/openitcockpit_mcp/skills/ ships prompt material that teaches a model how to chain these tools, plus a system prompt for an openITCOCKPIT assistant. It lives inside the package because the server also serves it over MCP - see Resources and prompts.

The oitc-* folders follow the Agent Skills layout, so cp -r src/openitcockpit_mcp/skills/oitc-* ~/.claude/skills/ is enough for Claude Code and Claude Desktop; for other clients they are plain Markdown. See src/openitcockpit_mcp/skills/README.md.

Resources and prompts

The same files are served over MCP, so a client that cannot copy folders into a skills directory still gets them:

• Resources at oitc://skills/<name>, one per file, text/markdown. The description a client shows is the SKILL.md frontmatter description.

• Prompts named after the workflow, for the oitc-* skills only. The two system-prompt files are resources but not prompts: a prompt is inserted as a message, and a system prompt belongs in the client's system field.

oitc-host-onboarding and oitc-config-change describe write workflows and are registered only when OITC_ENABLE_WRITE_TOOLS=true, exactly as the write tools are - offering a sequence the server cannot run would be worse than not offering it.

Security

• The http transport serves plain HTTP. Terminate TLS at a reverse proxy or keep the server on a trusted network.

• MCP_AUTH_TOKEN must differ from OITC_APIKEY; the server enforces this so the openITCOCKPIT key is never handed to a client.

• TLS verification against openITCOCKPIT is on by default. For a self-signed instance set OITC_CA_BUNDLE rather than disabling verification.

• Authentication is a shared static token, not OAuth 2.1 - a deliberate tradeoff for a server that authenticates as a single service user. See src/openitcockpit_mcp/auth.py.

Versioning

The image tag is this server's version, from MCP_VERSION. Two tags per release, and no others:

Semver: patch for fixes, minor for added tools, major for anything that breaks a client. But this is still 0.x - the tool set is settling, so a minor bump may break one too. Pin the exact version and read the CHANGELOG before you move.

Compatibility

openITCOCKPIT 5.6 or newer - one image serves every supported release.

All 39 tools were exercised against live instances on the 5.6 line, and the openITCOCKPIT API is backwards compatible, so newer instances are expected to work. One caveat: list_installed_software, list_pending_updates and list_pending_security_updates need the openITCOCKPIT agent's package endpoints and fail with an API error where that feature is absent.

Development

python -m venv .venv && . .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
./scripts/checks-docker.sh    # ruff, mypy and pytest, exactly as CI runs them

The script runs the suite inside the image the Dockerfile is based on, so a local run and a CI run use the same Python. Individually: ruff check ., mypy, pytest (206 tests).

Adding a tool: write it in the matching module under tools/read/ or tools/write/, decorate it with @mcp.tool(title=..., annotations=...) using a preset from tools/annotations.py, and the subpackage's register() picks it up - anything under tools/write/ is gated by OITC_ENABLE_WRITE_TOOLS automatically. A new module goes into that subpackage's READ_MODULES / WRITE_MODULES tuple, and a new tool into the call table in tests/test_tools_smoke.py, which runs every tool once against stubbed responses.

Build the image yourself with docker build -t oitc-mcp-server ..