# sysprobe-mcp

Standalone, token-efficient **MCP server for Linux system diagnostics and
desktop/hardware control**. Returns compact JSON with hard size limits so a
single tool call can never flood the model context.

It is distro-agnostic. For Arch/CachyOS package management (pacman/AUR) use the
companion **cachyos-mcp**, which embeds this server's tools.

## Tool groups

**Diagnostics (read-only, always available)**
- Filesystem/config: `list_directory_tree`, `read_config_snippet`, `grep_file`,
  `check_command_exists`
- Processes/resources: `get_process_top`, `get_process_info`,
  `inspect_process_io`, `find_processes`
- Sensors/power: `get_hardware_sensors`, `get_battery_health`
- System/hardware: `get_system_info`, `get_cpu_info`, `get_disk_usage`,
  `get_block_devices`, `list_usb_devices`, `list_pci_devices`, `get_gpu_info`
- systemd/logs: `get_service_status`, `list_services`, `list_failed_services`,
  `query_journalctl`, `get_boot_performance`
- Debugging: `list_coredumps`, `diagnose_crash`, `check_kernel_ring_buffer`
- D-Bus: `list_dbus_services`, `get_dbus_property`
- Desktop status: `get_brightness`, `get_power_profile`, `get_cpu_governor`,
  `get_volume`, `get_now_playing`, `bluetooth_status`, `bluetooth_devices`,
  `bluetooth_scan`, `get_kde_theme`, `list_color_schemes`, `list_desktop_apps`

**Control (mutating — needs `SYSCONTROL_ALLOW_ACTIONS=1`)**
- Bluetooth: `bluetooth_power`, `bluetooth_connect`, `bluetooth_disconnect`,
  `bluetooth_pair`
- Display/power: `set_brightness`, `set_power_profile`, `set_cpu_governor`
- Audio/media: `set_volume`, `set_mute`, `media_control`
- Apps: `launch_app`, `open_path`
- KDE: `set_color_scheme`, `set_global_theme`, `kde_notify`, `kwin_reconfigure`
- Services/processes: `control_service`, `kill_process`
- Session: `lock_session`, `suspend_system`

**Power (double-gated — also needs `SYSCONTROL_ALLOW_POWER=1`)**
- `power_action` (reboot / poweroff)

## Safety model

Read-only by default. Mutating tools return an explanatory error unless
`SYSCONTROL_ALLOW_ACTIONS=1` is set in the server environment. Genuinely
destructive actions (reboot/poweroff) need a second, independent flag
(`SYSCONTROL_ALLOW_POWER=1`) so they stay off even when ordinary actions are on.

## Run

```bash
uv run sysprobe-mcp                       # read-only
SYSCONTROL_ALLOW_ACTIONS=1 uv run sysprobe-mcp   # + control tools
```

## Register with Claude Code

```bash
claude mcp add sysprobe -s user \
  -e SYSCONTROL_ALLOW_ACTIONS=1 \
  -- uv --directory "/home/tom/Projekte/SE Projects/sysprobe-mcp" run sysprobe-mcp
```

## Optional system tools

Richer output when these are installed: `lm_sensors`, `upower`, `lsblk`,
`usbutils`, `pciutils`, `bluez-utils` (bluetoothctl), `powerprofilesctl`,
`cpupower`, `wireplumber`/`pulseaudio` (wpctl/pactl), `playerctl`, `qdbus6`,
`kreadconfig6` + `plasma-apply-*` (KDE), `brightnessctl`, `nvidia-utils`.