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.

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@88plug

Grok Build

grok plugin marketplace add 88plug/claude-code-plugins
grok plugin install os-control-mcp@88plug --trust

Confirm the server loaded:

/mcp

No setup needed — it uses the host's existing systemd/D-Bus tooling. Call os_diag first; it reports privilege, backends, and safety status.

Related MCP server: systemd-mcp

Features

Requirements

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

1. os_diag — health, privilege, backends, HIL/gating status

2. Observe — os_services / os_journal / os_resources / os_processes / os_pressure / os_net / os_disk / os_hardware / os_containers / os_sensors / os_session

3. Act — os_service / os_power / os_dbus / os_time / os_hostname / os_locale / os_notify

4. Confirm — os_wait and/or re-read status/journal

Tools

Observe (read-only)

Act (guarded)

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:

1. 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.

2. 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.)

3. Flag fallback (only when there's no human channel). If the client can't elicit, the server falls back to force/confirm 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.

4. 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.

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.

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.