mcp-systemd-crunchtools

MCP server for systemd unit management via D-Bus. Manages the full lifecycle of any systemd unit — not just Podman-managed containers: listing, status, lifecycle control, unit file authoring and decommissioning, journal queries, failed-unit and job triage, timers, host info, and login sessions.

Installation

# uvx (zero-install)
uvx mcp-systemd-crunchtools

# pip
pip install mcp-systemd-crunchtools

# Container
podman run \
  -v /run/dbus/system_bus_socket:/run/dbus/system_bus_socket \
  -v /etc/systemd/system:/etc/systemd/system:Z \
  --security-opt label=type:container_runtime_t \
  quay.io/crunchtools/mcp-systemd

The D-Bus socket mount is required for every tool. The /etc/systemd/system mount is only required for unit_file_write_tool and unit_file_remove_tool — omit it to run the server read/lifecycle-only.

Configuration

Variable	Required	Default	Description
DBUS_SYSTEM_BUS_SOCKET	No	/run/dbus/system_bus_socket	D-Bus system bus socket path
SYSTEMD_UNIT_DIR	No	/etc/systemd/system	Directory unit_file_write/remove operate on
SYSTEMD_EXTRA_PROTECTED_UNITS	No	—	Comma-separated units added to the built-in denylist

Protected units

unit_stop, unit_restart, unit_disable, unit_mask, and unit_file_remove refuse to act on a small built-in denylist of core system units (dbus, sshd, networking, logind, journald). This cannot be bypassed — it exists so an agent can't take down the box it's running on. Add more units with SYSTEMD_EXTRA_PROTECTED_UNITS.

Claude Code Integration

claude mcp add mcp-systemd-crunchtools \
  -- uvx mcp-systemd-crunchtools

Tools (21)

Units (3)

Tool	Description
unit_list	List loaded units or installed unit files
unit_status	Curated status (active state, PID, memory, CPU)
unit_show	Full property dump (deps, exec settings, cgroup)

Lifecycle (9)

Tool	Description
unit_start	Start a unit
unit_stop	Stop a unit (protected-list guarded)
unit_restart	Restart a unit (protected-list guarded)
unit_reload	Reload a unit's config without restarting
unit_enable	Enable a unit to start on boot
unit_disable	Disable a unit from starting on boot (protected-list guarded)
unit_mask	Mask a unit (protected-list guarded)
unit_unmask	Unmask a unit
daemon_reload	Reload systemd's unit file cache

Unit files (2)

Tool	Description
unit_file_write	Write a new unit file (backs up any file it overwrites)
unit_file_remove	Decommission: stop, disable, back up, remove (protected-list guarded)

Troubleshooting (3)

Tool	Description
journal_query	Filtered journal query (unit, priority, since/until, pattern, boot)
failed_units	List units in the 'failed' state
list_jobs	List pending/stuck jobs

Timers (1)

Tool	Description
timer_list	List timers with next/last elapse

System (2)

Tool	Description
system_status	Manager state: running/degraded, failed/job counts, version
hostinfo	Hostname, kernel, OS

Sessions (1)

Tool	Description
session_list	Who's logged in right now

License

AGPL-3.0-or-later