openITCOCKPIT-MCP-Server

# openITCOCKPIT MCP Server

An [MCP](https://modelcontextprotocol.io) server that exposes an
[openITCOCKPIT](https://openitcockpit.io/) 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](#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

```bash
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:

| Secret | Who presents it to whom |
|---|---|
| `MCP_AUTH_TOKEN` | **Clients → this server.** A random token you generate. |
| `OITC_APIKEY` | **This server → openITCOCKPIT.** The API key of a dedicated, least-privilege openITCOCKPIT user. |

```bash
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.

| Setting | Env var | Default |
|---|---|---|
| Client bearer token | `MCP_AUTH_TOKEN` | *(required for http)* |
| openITCOCKPIT API key | `OITC_APIKEY` | *(required)* |
| openITCOCKPIT base URL | `OITC_BASEURL` | *(required)* |
| Verify the instance's TLS certificate | `OITC_VERIFY_TLS` | `true` |
| CA bundle for a self-signed instance | `OITC_CA_BUNDLE` | *(unset)* |
| Request timeout, seconds | `OITC_TIMEOUT_SECONDS` | `20` |
| Register the write tools | `OITC_ENABLE_WRITE_TOOLS` | `false` |
| Cache scope-validation lookups | `OITC_SCOPE_CACHE_ENABLED` | `true` |
| Scope cache TTL, seconds | `OITC_SCOPE_CACHE_TTL_SECONDS` | `30` |
| Summarise the text half of a result | `OITC_COMPACT_CONTENT` | `false` |
| Transport, `http` or `stdio` | `OITC_TRANSPORT` | `http` |
| Bind address / port (http) | `OITC_HOST` / `OITC_PORT` | `0.0.0.0` / `8000` |
| Log level | `OITC_LOG_LEVEL` | `INFO` |
| Print the start-up banner | `OITC_SHOW_BANNER` | `true` |

---

## 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`.

```json
{
  "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](#mcp-registry) entry describes, and the form to hand to someone
who just wants to connect a desktop client:

```json
{
  "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:

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

> [!NOTE]
> Either way the server runs on the client's machine and holds the
> openITCOCKPIT API key there. The http transport keeps that key on one host
> you operate and gives clients a bearer token instead - prefer it when more
> than one person connects.

---

## Installation

### Docker

```bash
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](#versioning).

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

```bash
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`](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:

```bash
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](#quickstart) uses.

### From source

```bash
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](https://registry.modelcontextprotocol.io), 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](docs/read-tools.md)** · **[write tools](docs/write-tools.md)**.

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:

| Ask | Tools |
|---|---|
| "What is broken right now?" | `list_services_by_state`, `list_log_entries` |
| "Do we already know about db-01?" | `get_host_info`, `list_host_acknowledgements`, `list_host_downtimes` |
| "Why did web-03 flap last night?" | `list_host_state_changes`, `list_host_checks` |
| "Which hosts need security patches?" | `list_pending_security_updates` |
| "Is the monitoring itself keeping up?" | `get_monitoring_engine_stats` |
| "Which templates could web-05 use?" | `get_allowed_elements_for_container` |
| "Add web-05 with the Linux template" | `create_host` |

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

[docs/openitcockpit-api-notes.md](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.

<!-- The tool tables live in docs/read-tools.md and docs/write-tools.md. Keep
     this section to examples: 39 rows of signatures pushed everything else in
     the readme below the fold. -->

---

## 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](#resources-and-prompts).

| Skill | Use it for |
|---|---|
| [`system-prompt.md`](src/openitcockpit_mcp/skills/system-prompt.md) | Baseline assistant behaviour |
| [`system-prompt.de.md`](src/openitcockpit_mcp/skills/system-prompt.de.md) | The same, in German |
| [`oitc-incident-triage`](src/openitcockpit_mcp/skills/oitc-incident-triage/SKILL.md) | "What is broken?", in the order that rules things out |
| [`oitc-host-onboarding`](src/openitcockpit_mcp/skills/oitc-host-onboarding/SKILL.md) | Adding a host and its services without scope rejections |
| [`oitc-patch-review`](src/openitcockpit_mcp/skills/oitc-patch-review/SKILL.md) | Security and update overview across the estate |
| [`oitc-config-change`](src/openitcockpit_mcp/skills/oitc-config-change/SKILL.md) | Changing an object without blanking fields |
| [`oitc-capabilities`](src/openitcockpit_mcp/skills/oitc-capabilities/SKILL.md) | What the server cannot do, so a model does not invent it |

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](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` file