home-network-mcp

A personal MCP server that lets an LLM client (Claude Desktop, etc.) monitor my home network and home lab: which devices are online, whether key services are healthy, disk space, and uptime — across both my Windows Server 2022 home lab and a Raspberry Pi running Homebridge.

Alongside the MCP server, a Prometheus metrics exporter runs continuously, feeding real-time data into Grafana Cloud for dashboarding and alerting.

Why I built this

I wanted to understand how MCP actually works under the hood — not just use it, but build a server from scratch and see how tool schemas, async dispatch, and client/server message flow fit together. Wiring it up against my own home lab (a Windows Server 2022 environment) rather than a toy example forced me to deal with real problems: WinRM auth, parsing PowerShell's JSON output cleanly, timeouts on unreachable hosts, and so on.

Adding observability was a deliberate second layer — the MCP server is reactive (Claude asks, it answers), but a metrics exporter makes the monitoring continuous. Disk usage creeping up over weeks, a service that restarts every Tuesday because of Windows Update, a Pi that's been silently unreachable for hours — none of that is visible from on-demand polling alone.

It's also a deliberate split of responsibilities:

• Python / MCP — protocol layer: tool definitions, schemas, async orchestration
• PowerShell — automation layer for Windows targets: the actual Windows-native work (Get-Volume, Get-Service, WMI queries, Invoke-Command over WinRM)
• Bash over SSH — automation layer for Linux targets: querying systemd, df, /proc/uptime on my Raspberry Pi
• Prometheus + Grafana — observability layer: continuous metric collection, time-series storage, dashboarding and alerting

Status

scan_network is built and tested end-to-end on macOS against my home subnet, both via the MCP Inspector and Claude Desktop. The Windows-specific tools (check_service_health, check_disk_usage, check_uptime) are implemented but not yet verified against a live host — next step is pointing them at my Windows Server 2022 home lab over WinRM. The Raspberry Pi / Homebridge tools (check_pi_service, check_pi_disk_usage, check_pi_uptime) are newly added and not yet tested against the real Pi.

Tools exposed

Tool	Description
scan_network	Ping-sweeps a subnet, returns which hosts are up and their latency
check_service_health	Checks status of named Windows services on a host
check_disk_usage	Reports free/used space per volume on a Windows host, flags low free space
check_uptime	Returns last boot time and uptime for a Windows host
check_pi_service	Checks status of a systemd service (defaults to Homebridge) on the Pi over SSH
check_pi_disk_usage	Reports free/used space per mounted filesystem on the Pi, flags low free space
check_pi_uptime	Returns last boot time and uptime for the Pi

Metrics exposed

The exporter (exporter.py) continuously collects and serves the following Prometheus metrics:

Metric	Labels	Description
home_device_up	host	1 if the device responded to ping, 0 if unreachable
home_disk_free_ratio	host, volume	Fraction of disk space free (0.0–1.0) on Windows hosts
home_service_up	host, service	1 if the Windows service is running, 0 otherwise
home_uptime_seconds	host	System uptime in seconds for Windows hosts
home_pi_service_up	host, service	1 if the systemd service is active on the Pi
home_pi_disk_free_ratio	host, mount	Fraction of disk space free (0.0–1.0) on the Pi
home_pi_uptime_seconds	host	System uptime in seconds for the Pi

Requirements

• Python 3.10+
• PowerShell 7+ (pwsh) on PATH
• mcp[cli] and prometheus_client — see requirements.txt