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
The sanctioned OS "motor cortex" for an agent on a Linux box — control systemd, logind, journald, and D-Bus through structured interfaces, never raw PID hacks.
</div>
os-control-mcp is an MCP server — usable by any agent or MCP client (Claude Code, Cursor, Cline, Goose, Continue, your own MCP host, …) — that gives a model sanctioned control of a Linux host: manage systemd services and timers, query journald, read host resources and processes, send desktop notifications, drive the D-Bus buses, and manage power — all through the host's structured interfaces (systemctl, loginctl, journalctl, busctl), never raw kill/PID hacks. It is the system-service counterpart to screen-mcp's GUI control. Pure standard library, zero pip runtime deps. Linux + systemd.
Quickstart
Install the plugin in Claude Code:
/plugin marketplace add 88plug/os-control-mcp
/plugin install os-control-mcp@os-control-mcpThen confirm the server loaded and its tools are available:
/mcpNo setup needed — it uses the host's existing systemd/D-Bus tooling. Run the os_diag tool first; it reports your privilege level and which backends are present.
⚠️ Treat this plugin as privileged. It can stop services and power off the machine. The guards below make that hard to do by accident, but install it deliberately and disable it via /plugin when you're not using it.Use from any MCP client
It's a plain stdio MCP server — no Claude-Code lock-in. Point any MCP client at the launcher (or python3 server.py directly):
// e.g. Cursor / Cline / Goose / your own MCP host
{
"mcpServers": {
"os": { "command": "python3", "args": ["/path/to/os-control-mcp/server.py"] }
}
}It speaks MCP 2025-11-25 over stdio; the tools appear like any other MCP server.
Tools
Observe (read-only)
| Tool | What |
|---|---|
os_diag | health: privilege, backends, manager state, bus reachability, safety status |
os_services | inspect 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 | network — sockets (ss), ip addr/links/routes, wifi, NetworkManager |
os_disk | storage — 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 |
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; 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 | machine settings (timezone/NTP, hostname, locale/keymap) | writes need force=true; dry_run |
os_dbus | list/tree/introspect/get-property/set-property/call (system or session bus) | 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, 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's force/confirm flags 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 the force/confirm flags so headless automation still works — except severing a unit the agent stands on (sshd, NetworkManager, tailscaled, the session, goosed, …) which still needs force (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.
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 — it 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.