The Homelab MCP Server enables AI assistants to manage, deploy, and monitor homelab infrastructure through SSH, VM management, service installation, network mapping, and Proxmox integration.
SSH & Credential Management
Gather hardware/software info from remote systems, execute commands, and start interactive browser-based shell sessions
Set up a dedicated mcp_admin user with passwordless SSH key access and manage group memberships
Register, list, update, and remove SSH credentials for persistent server access
Network Discovery & Topology
Discover and map individual or multiple devices into a network site map database
Analyze network topology, track device changes, and get AI-driven deployment location suggestions
Infrastructure Lifecycle
Deploy, update, scale, and decommission infrastructure (Docker/LXD services, network changes)
Validate change plans, create backups of infrastructure state, and rollback to previous backups
Detect configuration drift via Terraform state refresh
VM & Container Operations
Deploy, start/stop/restart, monitor, retrieve logs from, and remove Docker and LXD containers/VMs
Service Installation & Management
List, inspect, and install homelab services (Jellyfin, Pi-hole, Ollama, Home Assistant, etc.)
Check device requirements before installation and monitor running service status
Terraform & Ansible Integration
Generate Terraform plans, destroy/refresh Terraform-managed services
Check Ansible deployment status and run playbooks with optional tags, extra vars, and dry-run mode
Proxmox Integration
Search community installation scripts and list all cluster resources (VMs, containers, nodes, storage, pools)
Get node/VM status, manage VM states (start, stop, reboot, suspend, etc.)
Create LXC containers and QEMU VMs, clone existing instances, and delete VMs/containers
Enables deployment and management of multi-service homelab stacks through Ansible playbooks, with support for system-level configuration, cross-service orchestration, and idempotent operations across multiple hosts.
Integration for test coverage reporting and CI/CD pipeline integration.
Supports Consul as a backend for Terraform state management in high-availability configurations.
Provides comprehensive container management including deployment, lifecycle control (start/stop/restart), status monitoring, log retrieval, and removal of Docker containers across homelab infrastructure.
Supports etcd as a backend for Terraform state management in high-availability configurations.
Integration for CI/CD workflows and repository management.
Enables automated deployment of Home Assistant for smart home automation with Pi GPIO integration, Pi Camera module support, Zigbee/Z-Wave hub capabilities, and energy monitoring.
Supports Intel Neural Compute Stick (NCS2) AI accelerator detection and optimization for AI inference workloads on homelab systems.
Provides automated deployment and management of Jellyfin media server through service templates.
Enables deployment and management of K3s lightweight Kubernetes clusters for container orchestration across homelab infrastructure.
Supports Kubernetes cluster deployment and management through K3s for container orchestration.
Provides reverse proxy configuration with SSL support as part of complete AI homelab stack deployments.
Enables deployment and management of Ollama local LLM server with Pi-optimized configurations for 4GB/8GB RAM, model recommendations based on available resources, and thermal/performance tuning for sustained workloads.
Supports ONNX model format for AI accelerator inference workloads including MemryX MX3, Coral TPU, Hailo-8, and Intel NCS2.
Provides automated deployment of Pi-hole network-wide ad blocking with support for both Docker Compose and Terraform deployments, including travel hotspot configuration.
Integration for running unit and integration tests with coverage reporting.
Python-based MCP server implementation with comprehensive infrastructure management capabilities.
Supports PyTorch model format for Hailo-8 AI accelerator inference workloads.
Provides optimized deployment and management of services on Raspberry Pi 4/5 with AI accelerator support, GPIO integration, Pi Camera module support, and thermal/performance optimization.
Uses SQLite for network topology mapping, device tracking, and change history management.
Supports TensorFlow and TensorFlow Lite model formats for AI accelerator inference, particularly for Coral Edge TPU and Hailo-8 accelerators.
Provides enterprise-grade infrastructure as code with full state management, idempotent deployments, drift detection, multi-backend support (local, S3, Consul, etcd), and clean resource lifecycle management for homelab services.
Enables deployment and management of TrueNAS network-attached storage with ZFS optimization.
Uses YAML for service template definitions including configuration for Ollama, Frigate NVR, Home Assistant, Pi-hole, Jellyfin, K3s, and TrueNAS.
Supports YOLOv5 object detection models for real-time AI inference with accelerators like MemryX MX3 and Coral TPU, achieving 80+ FPS on Raspberry Pi.
Supports Zigbee USB dongle integration through Home Assistant for smart home hub capabilities.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Homelab MCP Server install Frigate NVR on my Raspberry Pi with Coral TPU detection"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
AI-Powered Homelab Infrastructure Management via the Model Context Protocol
A Python MCP server that enables AI assistants to manage, deploy, and monitor homelab infrastructure. Tools span SSH discovery, VM management, service installation, network topology mapping, Proxmox operations, and credential management.
SSH Discovery -- Gather comprehensive hardware and software information from any system
Service Installation -- Deploy Jellyfin, Pi-hole, Ollama, Home Assistant, and more from templates
Proxmox Integration -- Full API access plus community script discovery
VM/Container Lifecycle -- Deploy, control, and remove Docker and LXD workloads
Network Mapping -- Discover devices, analyze topology, and track changes
Terraform and Ansible -- State-managed deployments with drift detection and playbooks
Credential Management -- Register servers once, connect without re-entering credentials
Related MCP server: remote-admin-mcp
# Install from PyPI (recommended — no clone needed)
uvx homelab-mcp
# Or clone and run from source
git clone https://github.com/washyu/homelab_mcp.git
cd homelab_mcp
uv sync && uv run python run_server.pyFor the full walkthrough (environment variables, MCP client configuration, first tool call), see the Setup Guide.
Guide | Description |
From zero to first tool call | |
All tools with arguments and examples | |
Environment variables and CLI options | |
Claude Desktop integration guide | |
REST/OpenAPI mode, endpoints, and error contract |
Setup -- The server generates an SSH key pair on first run (~/.ssh/mcp_admin_rsa)
Onboard a host -- Use setup_mcp_admin to create a managed user on the target system
Verify -- Use verify_mcp_admin to confirm passwordless SSH access
Manage -- Discover hardware, install services, control VMs, and map your network
The server communicates over stdio using the MCP protocol. Connect it to any MCP-compatible client (Claude Desktop, etc.) and interact through natural language.
Store SSH and Proxmox credentials once so the server auto-injects them on every connection:
# Store an SSH credential
homelab-mcp credentials add 192.168.1.10 admin
# Store an SSH key-based credential (stores the key file path in the keyring, not the key)
homelab-mcp credentials add 192.168.1.10 admin --key-path ~/.ssh/id_ed25519
# Store a Proxmox API credential
homelab-mcp credentials add 192.168.1.200 root@pam --type proxmox
# Update an existing credential — `add` is upsert; re-running replaces the stored entry
homelab-mcp credentials add 192.168.1.10 admin
# List stored credentials
homelab-mcp credentials list
homelab-mcp credentials list --type proxmox
# Remove a credential
homelab-mcp credentials remove 192.168.1.10The CLI provides full CRUD over credentials: add (create/update — upsert), list (read), remove (delete). There is no separate update subcommand — re-running add replaces both the keyring secret and the registry entry's auth type.
Credentials are stored in the OS keyring (libsecret on Linux, Keychain on macOS). When the OS keyring is unavailable (headless servers), credentials fall back to environment variables.
See Credentials CLI reference for full documentation.
From PyPI (uvx) — recommended:
{
"mcpServers": {
"homelab": {
"command": "uvx",
"args": ["homelab-mcp"]
}
}
}From source clone:
{
"mcpServers": {
"homelab": {
"command": "uv",
"args": ["run", "python", "run_server.py"],
"cwd": "/path/to/homelab_mcp"
}
}
}# Install with dev dependencies
uv sync --group dev
# Run tests (unit only, no Docker required)
uv run pytest tests/ -m "not integration"
# Code quality
uv run ruff check src/ tests/
uv run mypy src/See DEPLOYMENT.md for production deployment details.
src/homelab_mcp/
server.py # MCP server with JSON-RPC protocol
tool_schemas/ # Tool definitions (8 schema files)
tool_annotations.py # MCP annotation hints per tool
ssh_tools.py # SSH discovery and hardware detection
service_installer.py # Service installation framework
infrastructure_crud.py # Infrastructure lifecycle management
vm_operations.py # VM/container operations
sitemap.py # Network topology mapping
database.py # SQLite device tracking
error_handling.py # Centralized error handling
credential_store.py # OS keyring credential storage
log_filter.py # Credential redaction for log output
prompt_registry.py # MCP prompts registry
resource_readers.py # MCP resource read handlers
service_templates/ # YAML service definitions
tests/ # Unit and integration tests
docs/ # Full documentationProxmox community script integration powered by community-scripts/ProxmoxVE (MIT License).
Fork the repository
Create a feature branch
Write tests for new functionality
Ensure all tests pass
Submit a pull request
MIT License -- see LICENSE file for details.
Analyze the network topology and provide insights about the discovered devices
Inputs: no named parameters.
Discover multiple devices via SSH and store them in the network site map database
Inputs: targets (required).
Check the status of an Ansible-managed service deployment
Inputs: hostname (required), service_name (required), password, username.
Check if a device meets the requirements for a service installation
Inputs: hostname (required), service_name (required), password, username.
Clone a VM or container to create a new one
Inputs: node (required), vmid (required), new_vmid (required), full, +3 more.
Control VM state (start, stop, restart)
Inputs: action (required), vm_name (required), platform (required), device_id (required).
Create a backup of current infrastructure state
Inputs: device_ids, backup_name, backup_scope, include_data.
Create a new LXC container on Proxmox
Inputs: node (required), vmid (required), hostname (required), host, +10 more.
Create a new VM (QEMU) on Proxmox
Inputs: host (required), name (required), node (required), vmid (required), +10 more.
Safely remove a device from the network infrastructure. Stops services, removes the device from clusters, optionally migrates services per migration_plan, then deletes the sitemap row. Use remove_device for inventory-only deletion of one row; use purge_devices for bulk filter-based inventory deletion; use decommission_device when host-side cleanup (stop services, remove from clusters) is required before deletion.
Inputs: device_id (required), dry_run, force_removal, validate_only, +1 more.
Preview what decommission_device would affect without executing. Returns a structured dry-run report. No infrastructure is modified.
Inputs: device_id (required), force_removal, validate_only, migration_plan.
Delete a VM or container from Proxmox
Inputs: node (required), vmid (required), host, purge, +2 more.
Preview what delete_proxmox_vm would affect without executing. Returns a structured dry-run report. No VM is deleted.
Inputs: node (required), vmid (required), host, purge, +1 more.
Deploy new infrastructure based on AI recommendations or user specifications
Inputs: deployment_plan (required), validate_only.
Deploy a new VM/container on a specific device
Inputs: vm_name (required), platform (required), device_id (required), vm_config.
Destroy a Terraform-managed service and clean up all resources
Inputs: hostname (required), service_name (required), dry_run, password, +1 more.
Preview what destroy_terraform_service would affect without executing. Returns a structured dry-run report. No resources are destroyed.
Inputs: hostname (required), service_name (required), password, username.
Discover a device via SSH and store it in the network site map database. Recommended follow-up: run the configure_host_fingerprint prompt to capture per-host capability signals for drift detection.
Inputs: hostname (required), port, key_path, username.
Get change history for a specific device
Inputs: device_id (required), limit.
Get all discovered devices from the network site map database
Inputs: no named parameters.
Get detailed status of a Proxmox node (CPU, memory, uptime, etc.)
Inputs: node (required), host.
Get detailed information about a specific Proxmox community script
Inputs: script_name (required), category.
Get status of a specific VM or container
Inputs: node (required), vmid (required), host, vm_type.
Get detailed information about a specific service
Inputs: service_name (required).
Get the current status of an installed service
Inputs: hostname (required), service_name (required), password, username.
Get logs from a specific VM/container
Inputs: vm_name (required), platform (required), device_id (required), lines.
Get detailed status of a specific VM
Inputs: vm_name (required), platform (required), device_id (required).
Install a homelab service on a target device
Inputs: hostname (required), service_name (required), password, username, +1 more.
List all available homelab services that can be installed
Inputs: no named parameters.
List hosts that have credentials stored in the OS keyring registry. Call this before ssh_discover or ssh_execute_command to check whether a host has stored credentials. Returns hostname and username per entry.
Inputs: credential_type.
List all Proxmox cluster resources (VMs, containers, nodes, storage).
Inputs: host, resource_type.
List all registered servers with their SSH credentials and connection status
Inputs: active_only.
List all VMs/containers on a device
Inputs: device_id (required), platforms.
Manage a VM or container (start, stop, shutdown, reboot, reset, suspend, resume)
Inputs: node (required), vmid (required), action (required), host, +1 more.
Generate a Terraform plan to preview changes without applying them
Inputs: hostname (required), service_name (required), password, username, +1 more.
Bulk-delete sitemap rows by filter. Single mutually-exclusive filter per call selected by filter_type. Supported filter_types: 'hostname' (exact-match string, no glob/LIKE), 'last_seen_older_than_days' (integer N — rows where last_seen < now - N days, exclusive boundary; N=0 matches all rows older than this instant), 'status' (exact match string like 'error' or 'success'), 'ip_range' (CIDR string like '192.168.1.0/24' or '2001:db8::/32' — rows whose connection_ip is not a valid IP are silently skipped). Composite/ANDed filters are NOT supported (use two calls). Pass dry_run=true to preview the candidate set without deleting. Zero-match returns success with purged_count=0, never an error. Note: filter_type='status', value='error' covers ONLY status='error' rows; use purge_failed_discoveries for the broader failed-discovery filter (includes zombie hostnames). Use remove_device for inventory-only deletion of one row; use purge_devices for bulk filter-based inventory deletion; use decommission_device when host-side cleanup (stop services, remove from clusters) is required before deletion.
Inputs: value (required), filter_type (required), dry_run.
Preview the result of purge_devices without persisting. Returns the candidate set the bulk delete would touch. Read-only — no DB write. Phase 44 D-11.
Inputs: value (required), filter_type (required).
Remove sitemap rows for devices where discovery failed (status='error' or empty/null/'unknown' hostname). Pass dry_run=true to preview the removal candidates without deleting them. (Equivalent to purge_devices with the failed-discovery filter — preserves the 4-clause OR semantics; bare purge_devices(filter_type='status', value='error') matches ONLY status='error' rows, NOT zombie hostnames.) Use remove_device for inventory-only deletion of one row; use purge_devices for bulk filter-based inventory deletion; use decommission_device when host-side cleanup (stop services, remove from clusters) is required before deletion.
Inputs: dry_run.
Refresh Terraform state and detect configuration drift
Inputs: hostname (required), service_name (required), password, username.
Verify SSH connectivity to a registered server using keyring credentials. Does not write any credentials — credentials must already be stored via homelab-mcp credentials add <hostname> <username> in the CLI. Returns a status object with verified=true on successful handshake.
Inputs: hostname (required), username (required), port, display_name.
Delete a single sitemap row by device_id. Pure SQL DELETE on the sitemap row plus cascade DELETE on discovery_history rows for that device_id. No SSH dial, no Ansible runs, no Terraform plans on the handler call path. The keyring credential entry bound via ssh_credential_id is preserved — only the sitemap row is dropped, so a subsequent discover_and_map can re-bind without re-adding the credential. Pass dry_run=true to preview the would-delete row payload without writing. Use remove_device for inventory-only deletion of one row; use purge_devices for bulk filter-based inventory deletion; use decommission_device when host-side cleanup (stop services, remove from clusters) is required before deletion.
Inputs: device_id (required), dry_run.
Preview the result of remove_device without persisting. Returns the would-delete row payload. Read-only — no DB write, no keyring touch. Phase 44 D-11.
Inputs: device_id (required).
Remove a VM/container from a device
Inputs: vm_name (required), platform (required), device_id (required), force, +1 more.
Preview what remove_vm would affect without executing. Returns a structured dry-run report. No infrastructure is modified.
Inputs: vm_name (required), platform (required), device_id (required), force.
Rollback recent infrastructure changes
Inputs: backup_id (required), dry_run, device_ids, validate_only, +1 more.
Preview what rollback_infrastructure_changes would affect without executing. Returns a structured dry-run report. No infrastructure is modified.
Inputs: backup_id (required), device_ids, validate_only, rollback_scope.
Run an existing Ansible playbook for a service
Inputs: hostname (required), service_name (required), tags, password, +3 more.
Scale services up or down based on resource analysis
Inputs: scaling_plan (required), validate_only.
Scan for infrastructure drift against the sitemap. Returns a four-bucket coverage report — probed_ok (sitemap host probed successfully), unreachable (sitemap host that did not respond), unknown (reserved for Phase 39 — infrastructure present on a Proxmox hypervisor but absent from sitemap), and changed (reserved for Phase 39 — fingerprint differs from stored). All four buckets are always present in the response (empty arrays for Phase-39-reserved buckets) so client code can iterate without defensive checks. Each scan also returns a counts sub-dict mirroring bucket sizes and, when zero hosts were scanned (empty sitemap or filter narrowed to zero), a top-level guidance field pointing to the sitemap CRUD tools (discover_and_map, get_network_sitemap, purge_failed_discoveries, decommission_device). Recovery from credential-resolution failure is handled via 'homelab-mcp credentials add --type proxmox'.
Inputs: node, vm_type.
Search Proxmox community installation scripts from the community-scripts/ProxmoxVE repository
Inputs: query (required), category, include_metadata.
SSH into a system and gather hardware/system information. If credentials were stored with credentials add, username and password are auto-injected from the keyring — omit them. If authentication fails with 'No credentials found', run homelab-mcp credentials add <hostname> <username> in the terminal or call list_keyring_credentials to see what is already stored. Recommended follow-up after onboarding: run the configure_host_fingerprint prompt to capture per-host capability signals for drift detection.
Inputs: hostname (required), port, key_path, password, +1 more.
Execute a command on a remote system via SSH. If credentials were stored with credentials add, username and password are auto-injected from the keyring — omit them. If authentication fails with 'No credentials found', run homelab-mcp credentials add <hostname> <username> in the terminal or call list_keyring_credentials to see what is already stored.
Inputs: command (required), hostname (required), port, sudo, +2 more.
Start an interactive web-based shell session on a remote system. Opens a browser-based terminal with full TTY support for running interactive commands and scripts. Perfect for Proxmox community scripts or any interactive command-line tools. Requires HTTP server mode (--http flag). In stdio mode, this tool returns an error with setup instructions.
Inputs: hostname (required), port, password, username, +1 more.
Suggest optimal deployment locations based on current network topology and device capabilities
Inputs: no named parameters.
Update configuration of an existing device
Inputs: device_id (required), config_changes (required), validate_only, backup_before_change.
Merge fingerprint data (kernel, OS, package digest, capabilities) into a device's sitemap row. Top-level keys overwrite (last-write-wins). The capabilities sub-dict updates one level deep — each incoming top-level capability key REPLACES its stored entry entirely (NOT a recursive merge); stored capability keys not present in the call are preserved. Callers updating any field within a capability must pass the full capability dict. Run discover_and_map first to populate the device. See the configure_host_fingerprint prompt for the conversational workflow. Persists to DB and bumps updated_at; last_seen is preserved (Phase 38 REVIEW-FIX WR-03).
Inputs: hostname (required), fingerprint (required).
Preview the merge result of update_device_fingerprint without persisting. Returns the would-be merged fingerprint dict using the same merge rules: top-level overwrite + capabilities one-level overwrite (incoming capability keys replace stored entries entirely; not recursive). Read-only — no DB write, no last_seen or updated_at mutation. Phase 38 D-05c.
Inputs: hostname (required), fingerprint (required).
Validate infrastructure changes before applying them
Inputs: change_plan (required), validation_level.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 58 tools
While most tools target distinct actions, the abundance of deletion/removal variants (remove_device, purge_devices, decommission_device, etc.) and overlapping VM management tools create ambiguity. Agents may struggle to differentiate between subtly different tools like decommission_device and purge_failed_discoveries.
Tool names follow a consistent verb_noun pattern with snake_case (e.g., create_proxmox_vm, get_network_sitemap). Preview tools append '_preview' uniformly. Minor deviations like start_interactive_shell are clear but break the pattern slightly.
At 58 tools, the count is high for a single server. The broad scope (network discovery, Proxmox, services, Terraform) justifies many tools, but some could be consolidated (e.g., multiple deletion methods). The set feels slightly heavy but not extreme.
The tool set covers major lifecycle stages (create, read, update, delete, preview) across multiple domains. Notable gaps include lack of a direct sitemap update tool and limited service management beyond installation. However, the presence of preview tools for dangerous operations strengthens completeness.
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
Manage your own cloud with AI: deploy apps, push and ship custom Docker images, manage resources via your AI agent.
