LabscoMCP early access ↗
washyuMCP SERVER

Homelab MCP Server

Homelab operations as tool calls: SSH discovery, service installs from templates, VM and container lifecycle, network mapping, Proxmox, Terraform and Ansible.

by washyu ↗Network, Endpoint & Fleet ManagementCommunity

LABSCO SUMMARY

Preview variants on the operations that cannot be undone.

Removing a device, purging records, decommissioning a host — each has a matching preview call, so an agent can show its work before anything is destroyed. Credential handling is the other thing worth noting: register a host once and the server injects the credentials on every later connection, with key-based entries storing the key file path in the keyring rather than the key itself. Log output is filtered for credential redaction.

What it is

A Python MCP server for managing homelab infrastructure. It onboards a host by creating a managed admin user over SSH, then gives an assistant a broad surface — hardware discovery, service deployment, VM control, topology mapping — with credentials held in the OS keyring rather than typed each time.

What you get

  • Host onboarding and hardware discovery over SSH: create the managed user, confirm passwordless access, then gather hardware and software detail — setup_mcp_admin, verify_mcp_admin, ssh_discover, ssh_execute_command
  • Network topology: discover and map devices in bulk, read the sitemap, analyse the topology and track what changed — discover_and_map, bulk_discover_and_map, get_network_sitemap, analyze_network_topology, get_device_changes
  • Service installation from YAML templates — Jellyfin, Pi-hole, Ollama, Home Assistant and more — with requirement checks first — list_available_services, check_service_requirements, install_service, get_service_status
  • VM and container lifecycle for Docker and LXD workloads — deploy_vm, control_vm, get_vm_status, list_vms, get_vm_logs, remove_vm
  • Proxmox operations plus community script discovery — list_proxmox_resources, create_proxmox_lxc, create_proxmox_vm, clone_proxmox_vm, manage_proxmox_vm, search_proxmox_scripts
  • State-managed infrastructure with drift detection, backups and rollback, and Ansible playbook execution — deploy_infrastructure, scan_infrastructure_drift, create_infrastructure_backup, rollback_infrastructure_changes, run_ansible_playbook
  • Destructive operations paired with a preview variant that shows what would happen first — remove_device_preview, purge_devices_preview, decommission_device_preview

Requirements

SSH access to the machines you want managed. The server generates its own key pair on first run at ~/.ssh/mcp_admin_rsa. Install with uvx homelab-mcp — the package is homelab-mcp (version 1.8.0) — or clone and run uv sync && uv run python run_server.py. Credentials are stored in the OS keyring, libsecret on Linux and Keychain on macOS, falling back to environment variables on headless servers. Proxmox credentials are registered the same way with --type proxmox.

Setup effort

One command — uvx homelab-mcp

See installation options