Home Lab Developer Tools

Skills

Alerting Rules Write Prometheus alerting rules and configure Alertmanager routing for home lab notifications.

Triggers

User asks about creating or editing Prometheus alerts
User wants notifications when a service goes down or a threshold is breached
User mentions "alert", "alerting", "Alertmanager", "notification", or "firing"
User asks why alerts are not firing or notifications are not arriving
User wants to silence or inhibit specific alerts
User asks about alert routing or grouping configuration

MCP Tools

homelab_alertListhomelab_prometheusQueryhomelab_ntfySend

alerting-rules

Ansible Workflows Write and run Ansible playbooks for multi-node home lab provisioning and configuration management.

Triggers

Create or edit Ansible playbooks for home lab provisioning
Set up or modify the Ansible inventory for Pi nodes
Run playbooks from Windows using Docker or WSL
Write roles for deploying services, configuring networking, or hardening security
Debug Ansible task failures or connection issues
Manage group_vars and host_vars for environment-specific configuration

MCP Tools

homelab_inventorySynchomelab_nodeListhomelab_nodeExec

ansible-workflows

Backup and Recovery Configure and manage restic backups including scheduling, verification, and disaster recovery.

Triggers

User asks about backups, snapshots, or restore procedures
User wants to set up or verify a backup schedule
User asks "is my data backed up?" or "when was the last backup?"
User mentions "restic", "snapshot", "retention", or "disaster recovery"
User wants to restore a file, volume, or entire service from backup
User asks about backup storage, repository health, or integrity checks

MCP Tools

homelab_backupStatushomelab_backupRunhomelab_backupListhomelab_backupDiff

backup-recovery

Certificate Management Let's Encrypt, self-signed certs, renewal automation, NPM cert integration

Triggers

User asks about SSL certificates, HTTPS, or TLS on their home lab
User wants to check certificate expiry dates
User mentions "certbot", "Let's Encrypt", "SSL", "TLS", "HTTPS", or "certificate"
User wants to renew or provision a certificate
User asks about NPM certificate management
User wants to set up automatic certificate renewal
User reports browser certificate warnings

MCP Tools

homelab_certCheckhomelab_certRenewhomelab_certListhomelab_npmCerts

certificate-management

Disaster Recovery Full Pi disaster recovery -- backup verification, restore workflows, SD card imaging, and migration checklists

Triggers

User asks how to restore their Pi after a failure
User wants to verify backups are complete and recent
User needs to migrate to new hardware (new Pi, new SD card)
User wants to recover a specific Docker volume or service
User asks about backup strategy, retention, or coverage
User mentions "restore", "disaster recovery", "migration", or "SD card imaging"
User asks what changed between backups

MCP Tools

homelab_backupListhomelab_backupRestorehomelab_backupDiffhomelab_volumeBackuphomelab_backupStatushomelab_backupRun

disaster-recovery

DNS Management Manage AdGuard Home DNS filtering, blocklists, local DNS records, and query log analysis.

Triggers

User asks about DNS filtering, ad blocking, or AdGuard configuration
User wants to add or remove blocklists
User asks about DNS query logs or which domains are being blocked
User mentions "AdGuard", "DNS", "blocklist", "ad blocking", or "query log"
User asks why a website or service is not working (could be DNS blocking)
User wants to create local DNS records or rewrites
User asks about upstream DNS servers or DNS-over-HTTPS/TLS

MCP Tools

homelab_adguardStatshomelab_adguardFiltershomelab_adguardQueryLog

dns-management

Docker Compose Stacks Manage multi-file Docker Compose deployments on a Raspberry Pi home lab server.

Triggers

User asks to start, stop, update, or restart a Docker service
User mentions a specific service name (Grafana, AdGuard, Portainer, etc.)
User wants to pull new images or redeploy a stack
User asks about compose file structure or stack organization
User says "deploy", "compose up", "update containers", or "pull images"
User reports a service is down or not responding

MCP Tools

homelab_composeUphomelab_composeDownhomelab_composePullhomelab_composePs

docker-compose-stacks

Grafana Dashboards Create, import, export, and manage Grafana dashboards for home lab observability.

Triggers

User asks about creating or editing a Grafana dashboard
User wants to visualize specific metrics (CPU, memory, disk, network, container stats)
User mentions "Grafana", "dashboard", "panel", "graph", or "visualization"
User asks to export or back up a dashboard
User wants to add a new data source to Grafana
User asks about Grafana variables or templating

MCP Tools

homelab_grafanaSnapshothomelab_prometheusQuery

grafana-dashboards

Log Analysis Structured log querying, journald workflows, and container log searching

Triggers

User asks about system logs, journald, or syslog on their Pi
User wants to search Docker container logs for errors or patterns
User mentions "logs", "journalctl", "log search", "error logs", or "debug logs"
User wants to correlate events across multiple services
User asks why a service crashed or restarted
User wants to filter logs by priority, time range, or unit

MCP Tools

homelab_journalLogshomelab_logSearchhomelab_serviceLogs

log-analysis

Multi-Node Management Managing fleets, node inventory, parallel operations, cross-node monitoring

Triggers

User asks about managing multiple machines, servers, or Pis
User mentions "nodes", "fleet", "inventory", or "multi-node"
User wants to run commands on a specific named host
User asks about Ansible inventory or Tailscale peer discovery
User wants to compare status across multiple machines

MCP Tools

homelab_nodeListhomelab_nodeExechomelab_nodeStatushomelab_inventorySync

multi-node-management

Network Configuration Configure and manage AdGuard DNS, Nginx Proxy Manager, Tailscale VPN, and port mappings.

Triggers

User asks about DNS, ad blocking, or AdGuard configuration
User wants to set up a reverse proxy for a service
User asks about SSL certificates or HTTPS for local services
User mentions Tailscale, VPN, or remote access
User asks about ports, firewall rules, or iptables/nftables
User says "I can't reach [service]" or "DNS isn't working"
User wants to expose a service externally or via a custom domain

MCP Tools

homelab_networkInfohomelab_adguardStatshomelab_npmProxyHostshomelab_openPorts

network-configuration

Notification Workflows Ntfy setup, alert routing, and notification pipelines

Triggers

User asks about notifications, alerts, or push messages for their home lab
User wants to set up or configure Ntfy
User mentions "ntfy", "notifications", "alerts", "push notifications", or "webhooks"
User wants to send test notifications or debug notification delivery
User asks about routing Prometheus alerts to their phone
User wants to build automated notification pipelines

MCP Tools

homelab_ntfySendhomelab_ntfyTopicshomelab_alertList

notification-workflows

OS Update Management Unattended-upgrades config, kernel updates, reboot scheduling

Triggers

User asks about updating their Pi's OS or packages
User wants to check for available updates without applying them
User asks about unattended-upgrades or automatic updates
User mentions "apt upgrade", "kernel update", "reboot schedule", or "package management"
User wants to review what was recently installed or upgraded
User asks about update policies or scheduling maintenance windows

MCP Tools

homelab_aptUpdatehomelab_aptUpgradablehomelab_aptHistoryhomelab_kernelInfohomelab_systemdServices

os-update-management

Performance Tuning Kernel params, swap config, I/O scheduler, GPU memory split

Triggers

User asks about improving Pi performance or reducing latency
User mentions "slow", "swap", "memory", "GPU memory split", or "I/O scheduler"
User wants to optimize their Pi for Docker workloads
User asks about kernel parameters, sysctl tuning, or boot config
User wants to reduce SD card wear or optimize storage I/O
User asks about CPU governor, overclocking, or thermal management

MCP Tools

homelab_kernelInfohomelab_piStatushomelab_systemdServices

performance-tuning

Pi System Management Monitor and manage Raspberry Pi hardware - CPU temperature, throttling, memory, disk, and safe reboots.

Triggers

User asks about Pi health, temperature, CPU stats, or throttling
User wants to check memory or disk usage on the Pi
User requests a reboot or shutdown of the Pi
User mentions "vcgencmd", "thermal", "throttle", or "system status"
User asks "is the Pi okay?" or "is the server overheating?"

MCP Tools

homelab_piStatushomelab_piReboothomelab_diskUsage

pi-system-management

Reverse Proxy Management Configure Nginx Proxy Manager for reverse proxying, SSL certificates, and access control.

Triggers

User asks about reverse proxy setup or configuration
User wants to expose a service via a custom domain
User asks about SSL certificates, HTTPS, or Let's Encrypt
User mentions "NPM", "Nginx Proxy Manager", "reverse proxy", or "proxy host"
User asks about access lists or restricting access to a service
User wants to see what services are proxied
User says "I can't reach [service] via my domain"

MCP Tools

homelab_npmProxyHostshomelab_npmCertshomelab_certCheck

reverse-proxy-management

Secrets Management Managing credentials with Vaultwarden, environment variables, Docker secrets, and security auditing

Triggers

User asks about managing passwords, API keys, or credentials in their home lab
User wants to set up or configure Vaultwarden
User asks about Docker secrets vs environment variables
User mentions "secrets", "credentials", "passwords", "API keys", or "Vaultwarden"
User wants to audit their setup for hardcoded or weak credentials
User asks about securing environment variables in Docker Compose
User wants to rotate credentials or tokens

MCP Tools

homelab_containerScanhomelab_ufwStatushomelab_fail2banStatushomelab_openPorts

secrets-management

Security Hardening Harden the home lab with UFW firewall rules, fail2ban, SSH lockdown, and container security practices.

Triggers

Configure or modify UFW firewall rules on the Pi
Set up or tune fail2ban jails for SSH, Nginx, or other services
Lock down SSH to key-only authentication
Harden Docker containers (non-root users, read-only filesystems, capability dropping)
Secure Vaultwarden, Nginx Proxy Manager, or other exposed services
Protect the Docker socket from unauthorized access
Audit the current security posture of the home lab

MCP Tools

homelab_ufwStatushomelab_fail2banStatushomelab_openPortshomelab_containerScan

security-hardening

Service Monitoring Set up and use Prometheus, Grafana, Uptime Kuma, and Alertmanager for home lab observability.

Triggers

User asks about monitoring, metrics, dashboards, or alerts
User wants to add a new scrape target to Prometheus
User asks to create or modify a Grafana dashboard
User wants to set up Uptime Kuma monitors for a service
User mentions "Prometheus", "Grafana", "alert", "uptime", or "ntfy"
User asks why they are not receiving notifications for outages
User wants to check if all services are healthy

MCP Tools

homelab_serviceHealthhomelab_serviceLogshomelab_serviceRestarthomelab_prometheusQueryhomelab_uptimeKumaStatus

service-monitoring

SSH Management Manage SSH keys, harden SSH configuration, set up tunnels, and troubleshoot connection issues.

Triggers

Generate or rotate SSH keys for Pi access
Harden sshd_config on the Raspberry Pi
Set up SSH tunnels or port forwarding to home lab services
Debug SSH connection failures or timeouts
Configure SSH agent forwarding from Windows to the Pi
Manage authorized_keys entries for multiple users or machines

MCP Tools

homelab_sshTest

ssh-management

Storage Management Manage Samba shares, Syncthing file sync, Docker volumes, and disk space on the Raspberry Pi.

Triggers

Create or modify Samba shares on the Pi
Configure Syncthing for file synchronization between devices
Manage Docker volumes (named volumes vs bind mounts)
Monitor disk usage and free space on the Pi
Clean up unused Docker images, volumes, or build cache
Set up automated cleanup or log rotation strategies

MCP Tools

homelab_diskUsagehomelab_volumeBackup

storage-management

Troubleshooting Debug container crashes, network connectivity issues, Pi hardware problems, and service failures.

Triggers

Diagnose why a Docker container is crashing or restarting
Debug network connectivity between services or from external clients
Investigate Raspberry Pi hardware issues (throttling, overheating, undervoltage)
Troubleshoot systemd service failures (Cockpit, Samba, node_exporter)
Resolve DNS issues with AdGuard Home
Debug reverse proxy errors in Nginx Proxy Manager
Investigate general "service is down" reports from Uptime Kuma or Homepage

MCP Tools

homelab_serviceLogshomelab_serviceHealthhomelab_piStatushomelab_journalLogshomelab_logSearchhomelab_healthCheckhomelab_diagnostics

troubleshooting

Rules

Name	Scope	Description
Ansible Best Practices		Flag Ansible antipatterns including non-FQCN modules, missing tags, and shell commands when modules exist.
Backup Coverage		Flag Docker Compose services with persistent data that lack backup coverage.
Compose Arm64		Flag Docker Compose issues specific to arm64 Raspberry Pi deployments including incompatible images and missing healthchecks.
Exposed Ports		Flag Docker Compose services with exposed host ports that should use a reverse proxy instead.
Homelab Secrets		Flag hardcoded credentials, IP addresses, SSH keys, and secrets in home lab code and configuration files.
Inventory Consistency		Flag inconsistencies between node registry and inventory or configuration files.
Privileged Containers		Flag Docker Compose services running with elevated privileges or missing security restrictions.
Resource Limits		Flag Docker Compose services without memory or CPU limits set.
Ssh Safety		Flag dangerous SSH commands that could cause data loss or system damage on the Raspberry Pi.
Weak Credentials		Flag default, weak, or improperly stored credentials in Docker Compose files and environment configs.
Yaml Conventions		Enforce YAML formatting conventions for consistency across compose files, Ansible playbooks, and monitoring configs.

MCP Tools

AdGuard Home 3

Name	Description
homelab_adguardStats	AdGuard Home DNS statistics and query counts
homelab_adguardFilters	List AdGuard Home filter lists
homelab_adguardQueryLog	Search the AdGuard Home DNS query log

Backups 6

Name	Description
homelab_backupStatus	Check latest restic backup snapshots
homelab_backupRun	Trigger a restic backup
homelab_backupList	List all restic backup snapshots
homelab_backupRestore	Restore files from a restic backup snapshot
homelab_backupDiff	Show difference between two backup snapshots
homelab_volumeBackup	Back up a Docker volume to restic

Connectivity & Diagnostics 3

Name	Description
homelab_sshTest	Test SSH connectivity to the Raspberry Pi
homelab_healthCheck	Comprehensive self-test: SSH, Docker, required tools
homelab_diagnostics	Collect debug info: OS, kernel, Docker, memory, disk, network

Docker & Compose 10

Name	Description
homelab_composeUp	Start Docker Compose stacks
homelab_composeDown	Stop Docker Compose stacks
homelab_composePull	Pull latest Docker images for compose stacks
homelab_composePs	List running Docker Compose containers
homelab_serviceHealth	Check Docker container health status
homelab_serviceLogs	Tail recent logs from a Docker container
homelab_serviceRestart	Restart a Docker container
homelab_containerScan	Scan running container images for vulnerabilities using Trivy
homelab_logSearch	Search across Docker container logs with grep patterns
homelab_journalLogs	Query systemd journal logs with filters

Inventory & Nodes 4

Name	Description
homelab_inventorySync	Discover nodes from Ansible inventory or Tailscale network
homelab_nodeList	List all managed nodes and their connection status
homelab_nodeStatus	Get system status for a specific node
homelab_nodeExec	Execute a shell command on a specific node

Monitoring 5

Name	Description
homelab_prometheusQuery	Run a PromQL query against Prometheus
homelab_grafanaSnapshot	Export a Grafana dashboard configuration
homelab_uptimeKumaStatus	Get status of all Uptime Kuma monitors
homelab_alertList	List alerts from Alertmanager
homelab_speedtestResults	Get recent speedtest results

Notifications 2

Name	Description
homelab_ntfySend	Send a push notification via Ntfy
homelab_ntfyTopics	List Ntfy topics and recent messages

Raspberry Pi 2

Name	Description
homelab_piStatus	Raspberry Pi status: CPU temp, memory, disk, uptime, throttle state
homelab_piReboot	Safely reboot the Raspberry Pi

System & Security 10

Name	Description
homelab_diskUsage	Get detailed disk usage breakdown
homelab_kernelInfo	Kernel version, boot parameters, loaded modules
homelab_systemdServices	List systemd units or get status of a specific unit
homelab_aptUpdate	Run apt update and list upgradable packages
homelab_aptUpgradable	List upgradable packages with versions
homelab_aptHistory	Show recent apt install, upgrade, and remove history
homelab_networkInfo	IP addresses, interfaces, DNS, and Tailscale status
homelab_openPorts	Scan for listening TCP ports and map to processes
homelab_ufwStatus	List UFW firewall rules and status
homelab_fail2banStatus	List fail2ban jails, banned IPs, and ban counts

TLS & Reverse Proxy 5

Name	Description
homelab_certCheck	Check SSL certificate expiry, issuer, and fingerprint
homelab_certRenew	Trigger Let's Encrypt certificate renewal
homelab_certList	List managed SSL certificates from certbot and NPM
homelab_npmCerts	List Nginx Proxy Manager SSL certificates
homelab_npmProxyHosts	List Nginx Proxy Manager proxy host configs

Installation

Option A: npm (recommended)
npm install -g @tmhs/homelab-mcp
Option B: from source
git clone https://github.com/TMHSDigital/Home-Lab-Developer-Tools.git
cd Home-Lab-Developer-Tools/mcp-server && npm install && npm run build
Add to Cursor MCP config (.cursor/mcp.json):
{"mcpServers":{"homelab":{"command":"npx","args":["-y","@tmhs/homelab-mcp"],"env":{"HOMELAB_PI_HOST":"192.168.1.x","HOMELAB_PI_USER":"pi","HOMELAB_PI_KEY_PATH":"~/.ssh/id_rsa"}}}}
Configure SSH: Set HOMELAB_PI_HOST, HOMELAB_PI_USER, and HOMELAB_PI_KEY_PATH in the env block above. See .env.example for all optional vars (Grafana, AdGuard, Ntfy, etc.).
Open any project in Cursor and the 22 skills, 11 rules, and 50 MCP tools are available immediately.

Changelog

v0.10.0 2026-04-05

Added

2 new MCP tools for testing and diagnostics
`homelab_healthCheck` -- comprehensive self-test (SSH, Docker, curl, restic, certbot, systemd)
`homelab_diagnostics` -- collect debug info bundle (OS, kernel, Docker, memory, disk, network)
Integration tests with mocked SSH -- first tests covering actual tool handler logic
E2E test suite gated behind `HOMELAB_TEST_PI=true` env var for live Pi testing
`.github/workflows/e2e.yml` CI workflow for manual/scheduled E2E runs against a real Pi
Input validation tests for both new tools

v0.9.0 2026-04-05

Added

4 new MCP tools for multi-node management
`homelab_nodeList` -- list all managed nodes and their connection status
`homelab_nodeExec` -- execute a command on a specific node by name (requires confirm=true)
`homelab_nodeStatus` -- get system status for a specific node (uptime, CPU, memory, disk)
`homelab_inventorySync` -- discover nodes from Ansible inventory or Tailscale
1 new skill
`multi-node-management` -- managing fleets, node inventory, parallel operations, cross-node monitoring
1 new rule
`inventory-consistency` -- flag nodes in config missing from HOMELAB_NODES registry
`HOMELAB_NODES` env var for multi-node SSH configuration (JSON object)
`HOMELAB_ANSIBLE_INVENTORY` env var for Ansible inventory path
Input validation tests for all 4 new tools

Changed

**Infrastructure refactor:** `ssh-api.ts` now supports a node registry via `HOMELAB_NODES` env var
`execSSH()` accepts an optional `node` parameter to target specific nodes
All 44 existing tools now accept an optional `node` parameter (defaults to primary Pi)
New `node-param.ts` utility provides shared zod schema fragment for the node parameter

Changed

**Infrastructure refactor:** `ssh-api.ts` now supports a node registry via `HOMELAB_NODES` env var
`execSSH()` accepts an optional `node` parameter to target specific nodes
All 44 existing tools now accept an optional `node` parameter (defaults to primary Pi)
New `node-param.ts` utility provides shared zod schema fragment for the node parameter

View full changelog on GitHub →

Home Lab Developer Tools

Skills

Rules

MCP Tools

Installation

Changelog

Related Tools