hwprobe-mcp

A hardware probe for AI agents, over MCP.

hwprobe-mcp is a Model Context Protocol server that gives an AI agent (any MCP client) both deep hardware inventory and live sensor telemetry through a small set of clean, JSON-returning tools.

Most "system monitor" MCP servers are thin psutil wrappers that only report utilization. hwprobe-mcp deliberately fuses three layers so an agent gets the whole picture in one place:

Everything degrades gracefully: a missing tool, an absent GPU, or a lack of root privileges becomes a warnings[] entry, never a crash.

Tools

Every tool returns a consistent envelope:

{
  "ok": true,
  "platform": "Linux",
  "sources": ["psutil", "lm-sensors"],
  "warnings": ["nvidia-smi: NVIDIA driver not loaded"],
  "data": { "...": "..." }
}

Related MCP server: DivLens MCP

Install

Requires Python 3.10+.

# from source (until published to PyPI)
git clone git@github.com:notreallycheeks/hwprobe-mcp.git
cd hwprobe-mcp
pip install -e .

For the fullest data on Linux, install the native helpers (all optional):

sudo apt install lm-sensors smartmontools pciutils util-linux dmidecode
sudo sensors-detect --auto      # one-time, sets up lm-sensors

NVIDIA GPU telemetry uses the nvidia-smi binary shipped with the NVIDIA driver — there is no pip extra to install.

Checking what's installed

hwprobe works with whatever is present and degrades gracefully — but it will also tell you what's missing and how to install it. Run the built-in doctor:

hwprobe-mcp --doctor

...or have your agent call the check_dependencies tool. Each missing backend comes with the exact install command for your platform's package manager, and the JSON-returning tools embed the same hint in their warnings.

Two backends need elevated privileges to return data — smartctl (disk SMART) and dmidecode (motherboard/BIOS/DIMM). Run the server as root, or grant scoped passwordless sudo just for smartctl so disk_health works from the unprivileged server:

echo "$USER ALL=(root) NOPASSWD: $(command -v smartctl)" | sudo tee /etc/sudoers.d/hwprobe-smartctl
sudo chmod 0440 /etc/sudoers.d/hwprobe-smartctl

hwprobe automatically uses sudo -n smartctl when it isn't root, so no code changes are needed.

Fleet: every machine on your tailnet, in one view

hwprobe-fleet turns hwprobe into a fleet monitor so an AI agent can see which machine is busy and which is idle before it delegates work. Each host runs a tiny agent; a hub (or any agent) aggregates them; agents read the result over MCP, CLI or HTTP.

Claude usage

For every Claude Code account signed in on a host (~/.claude, $CLAUDE_CONFIG_DIR, Orca managed-account folders), the agent reports email, plan, the 5-hour and 7-day windows, per-model weekly windows and reset times — the same numbers as Claude Code's /usage — plus whatever Orca tracks (orca account list --json) when Orca is installed. Tokens are read only to make that request and never leave the machine.

HOST     OS     STATUS  CPU  RAM           DISK                       GPU             CLAUDE (5h / 7d / per-model)       AGE
alpha*   Linux  ok      5%   12/64G (19%)  310G free/954G (68% used)  RTX 4070 2%     me@example.com 5h:93% 7d:31% f:24% 2s

Install the agent on a machine

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/notreallycheeks/hwprobe-mcp/main/scripts/install-agent.sh | \
  HWPROBE_FLEET_HUB=http://hub-host:7790 HWPROBE_FLEET_TOKEN=<token> bash

# Windows
$env:HWPROBE_FLEET_HUB='http://hub-host:7790'; $env:HWPROBE_FLEET_TOKEN='<token>'
irm https://raw.githubusercontent.com/notreallycheeks/hwprobe-mcp/main/scripts/install-agent.ps1 | iex

Both create a venv, install this package, write fleet.json, and register a login service (systemd --user / launchd / Task Scheduler). Leave the hub variables out to run peer-to-peer only. Everything is per-user; nothing needs root.

Run the hub

See deploy/README.md: docker compose -f deploy/docker-compose.yml up -d on the machine that stays up, then claude mcp add --transport http fleet-hub http://<host>:7790/mcp --header "Authorization: Bearer <token>" on every machine. The hub only ever receives connections, so Docker NAT is fine.

Install the Orca panel

This repository is also an Orca plugin catalog (orca-catalog.json). In Orca, open Settings → Plugins → Add catalog, enter https://github.com/notreallycheeks/hwprobe-mcp.git and install Fleet, or open orca://plugins/notreallycheeks.hwprobe-fleet?catalog=https://github.com/notreallycheeks/hwprobe-mcp.git. Then set the hub URL and token under Settings → Plugins → Fleet. For a new release, commit the plugin, run orca plugin release-entry orca-plugin and add its entry to the top of releases.

Security model

Agents listen only on loopback and the Tailscale address and refuse non-tailnet source IPs. The hub requires a bearer token (generated on first start if you do not set one) because its Docker port is reachable from every interface of its host. Reports carry hostnames, resource figures and Claude account e-mails/usage — fine for a personal tailnet, so keep the token private.

Use with an MCP client

Add it to your MCP client's server config:

{
  "mcpServers": {
    "hwprobe": {
      "command": "hwprobe-mcp"
    }
  }
}

Then ask your agent things like "what's this machine's CPU and how hot is it right now?" or "check disk SMART health and current GPU power draw."

Try it without an MCP client

--selftest runs every collector and dumps the JSON an agent would see — handy for verifying your box and for CI:

# from the repo root, before install:
PYTHONPATH=src python -m hwprobe_mcp --selftest | jq .
# or, once installed (pip install -e .):
hwprobe-mcp --selftest

Platform support

Note: deep motherboard/BIOS/DIMM inventory (dmidecode) and full SMART data need root/admin. Without it, hwprobe-mcp returns everything it can read and flags the rest in warnings.

Roadmap

• Windows deep sensors via a bundled LibreHardwareMonitor bridge

• macOS powermetrics power/thermal integration (opt-in, needs sudo)

• AMD/Intel GPU telemetry (rocm-smi, intel_gpu_top)

• Optional streaming/subscribe tool for continuous sensor sampling

• Publish to PyPI + uvx hwprobe-mcp

License

MIT © 2026 notreallycheeks