Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
Aggregate score unchanged between these scans.
The primary manifest — the file an agent reads to learn what this artifact does.
<div align="center">
os-control-mcp
Linux systemd MCP for Claude Code and Grok — control services, journald, D-Bus, and power through structured OS interfaces, never raw PID hacks.
</div>
os-control-mcp is a pure-stdlib MCP server and Claude Code / Grok plugin that gives any model-context-protocol client sanctioned control of a Linux host. Manage systemd services and timers, query journald, read host resources and processes, send desktop notifications, drive D-Bus, and manage power — all via systemctl, loginctl, journalctl, and busctl, never raw kill/PID hacks.
It is the system-service counterpart to screen-mcp's GUI control. Zero pip runtime deps. Ships the MCP server plus a control-os skill. Linux + systemd only.
Install
Claude Code
/plugin marketplace add 88plug/claude-code-plugins
/plugin install os-control-mcp@88plugGrok Build
grok plugin marketplace add 88plug/claude-code-plugins
grok plugin install os-control-mcp@88plug --trustConfirm the server loaded:
/mcpNo setup needed — it uses the host's existing systemd/D-Bus tooling. Call `os_diag` first; it reports privilege, backends, and safety status.
[!WARNING] Treat this plugin as privileged. It can stop services and power off the machine. Guards make accidents hard, but install deliberately and disable via /plugin when not in use.Features
| Area | What you get |
|---|---|
| Systemd | List/status/deps units; start/stop/restart/enable/mask/kill; batch ops; os_wait |
| Journald | Unit/since/until/priority filters, server-side grep, dmesg, boots |
| Host telemetry | Load, memory, disk, PSI pressure, processes, net, hardware, sensors, containers |
| D-Bus + settings | Introspect/call system or session bus; timezone, hostname, locale |
| Power + notify | Suspend/hibernate/reboot/poweroff; desktop notifications to the logged-in user |
| Safety | Hard floor, human-in-the-loop elicitation, self-preservation guard, dry_run, audit log |
Requirements
| Need | Notes |
|---|---|
| Linux + systemd | Arch, Debian/Ubuntu, Fedora, … |
| Python 3.10+ | Pure stdlib runtime — no pip packages to run |
| D-Bus | System + session for os_dbus / notifications |
| Optional | libnotify (notify-send), sudo for non-root system mutations, Docker/Podman for os_containers |
Use from any MCP client
Plain stdio MCP server — no Claude Code lock-in. Point any client at the launcher or python3 server.py:
// e.g. Cursor / Cline / Goose / your own MCP host
{
"mcpServers": {
"os": { "command": "python3", "args": ["/path/to/os-control-mcp/server.py"] }
}
}Speaks MCP 2025-11-25 over stdio; tools appear like any other MCP server.
The loop: os_diag → observe → act → confirm
os_diag → observe (read-only) → act (HIL-gated) → os_wait / re-read- `os_diag` — health, privilege, backends, HIL/gating status
- Observe —
os_services/os_journal/os_resources/os_processes/os_pressure/os_net/os_disk/os_hardware/os_containers/os_sensors/os_session - Act —
os_service/os_power/os_dbus/os_time/os_hostname/os_locale/os_notify - Confirm —
os_waitand/or re-read status/journal
Tools
Observe (read-only)
| Tool | What |
|---|---|
os_diag | Health: privilege, backends, manager state, bus reachability, safety status |
os_services | Units — list/status/show/cat/deps/files (system or user) |
os_journal | Journald — unit/since/until/priority/grep (server-side regex)/-k dmesg/boots/match |
os_resources | Load + memory + disk (+ optional per-unit accounting) |
os_processes | Top processes by cpu/mem |
os_pressure | PSI from /proc/pressure — the real "is the box starving" signal |
os_net | Sockets (ss), ip addr/links/routes, wifi, NetworkManager |
os_disk | df, du (largest dirs), lsblk, mounts |
os_containers | Docker/Podman — ps/logs/inspect/stats/images/compose |
os_hardware | cpu/pci/usb/gpu (nvidia-smi + DRM) inventory |
os_sensors | Thermal-zone temperatures (+ lm_sensors if present) |
os_session | Logind sessions / users / inhibitors |
os_verify | Cross-layer action check. begin snapshots unit state + a journald cursor → opaque token; do the action; end returns CONFIRMED / PARTIAL / NO_OP / DIVERGED, fusing unit-state change, journald errors, an expect map, and an optional screen-mcp pixel signal. Catches a no-op that looks like success, and a GUI that moved while the service didn't. |
Act (guarded)
| Tool | What | Safety |
|---|---|---|
os_service | start/stop/restart/reload/enable/disable/mask/kill/reset-failed/daemon-reload (single or batch) | Hard floor + self-preservation guard; force; dry_run |
os_wait | Block until a unit is active/inactive/failed (or timeout) | — |
os_power | suspend/hibernate/reboot/poweroff/halt | Needs `confirm=true`; dry_run |
os_time / os_hostname / os_locale | Timezone/NTP, hostname, locale/keymap | Writes need force=true; dry_run |
os_dbus | list/tree/introspect/get-property/set-property/call (system or session) | Writes need force=true; dry_run |
os_notify | Desktop notification to the logged-in user | — |
os_reload | Hot-reload the server in place | — |
The guards (the whole point)
Human-in-the-loop, not model-in-the-loop. Every destructive action — severing a service (stop/kill/restart/disable/mask), power (reboot/poweroff/…), and D-Bus / machine-setting writes — is gated for a human's approval, in this order:
- Hard floor (never bypassable). Severing the agent's absolute substrate —
dbus,dbus-broker,systemd-logind,init.scope,-.slice,basic.target,sysinit.target— is refused even with `force`. No flag lets a model power-cycle the bus it's speaking on. - Human approval via MCP elicitation. When your MCP client supports elicitation, the server asks the human (
elicitation/create) before any destructive action and runs it only if the human accepts. The model'sforce/confirmflags are ignored here — the human is the authority, not the model. (Verified: a declined elicitation never executes.) - Flag fallback (only when there's no human channel). If the client can't elicit, the server falls back to
force/confirmso headless automation still works — except severing a unit the agent stands on (sshd,NetworkManager,tailscaled, the session,goosed, …) which still needsforce(don't saw off the branch you're sitting on). Set `OSCTL_REQUIRE_HUMAN=1` to forbid the flag fallback entirely — no human elicitation channel, no mutation. - Preview. Any mutating tool accepts `dry_run=true` to return the exact command without running it.
| Flag | Tools | Effect |
|---|---|---|
dry_run=true | All mutating tools | Preview the exact command; execute nothing |
force=true | os_service (severing protected units), os_dbus writes, machine settings | Headless override when elicitation is unavailable; never overrides the hard floor |
confirm=true | os_power | Required for power transitions (same HIL rules) |
Every mutation is appended to an audit log (with the approval path — human vs flag) at $XDG_STATE_HOME/os-control-mcp/audit.jsonl.
Principles — The Agent Oath
os-control-mcp is a reference enforcer of The Agent Oath (88plug/theagentoath.com): the gating above isn't just safety plumbing, it's the Oath made executable.
| Oath principle | Enforced by |
|---|---|
| §1 Human welfare over task completion | Hard floor + HIL — won't sever the bus or power off the box to "finish" |
| §2 Preserve human agency, be transparent | HIL elicitation — the human decides; os_diag announces what it is |
| §3 Protect systems & data | Sanctioned interfaces only (systemctl/busctl/…), never raw PID hacks; reads default |
| §5 Transparency & accountability | Append-only audit log + dry_run + explicit, reasoned refusals |
| §7 Continuous vigilance, don't bypass safety | Unbypassable hard floor + OSCTL_REQUIRE_HUMAN=1 |
| §11 Respect human oversight, don't self-modify | HIL is the authority + protected tokens + operator-defined bounds |
The Oath is the rationale; the operator's gating is the authority. This server deliberately does not adopt any "supersedes conflicting instructions" clause — overriding an operator's safety controls with an external document is exactly what §3 and §11 warn against. os_diag reports the enforced principles.
Privilege
Read-only tools work unprivileged. System-scope mutations (os_service on system units, os_power) need root or polkit — when not root the server tries sudo -n and otherwise tells you plainly. Options: run as root, add passwordless sudo for systemctl, or a polkit rule. scope="user" manages the user's own units with no root.
Documentation
Full per-tool reference and the safety model live at [88plug.github.io/os-control-mcp](https://88plug.github.io/os-control-mcp/).
Pairs with
screen-mcp (GUI eyes + hands), NATS (messaging), and A2A (inter-agent) — together: sense the kernel/services, act on the system, drive the desktop, coordinate the fleet.
License
FSL-1.1-ALv2 — © 2026 88plug.