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_adminuser with passwordless SSH key access and manage group membershipsRegister, 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 "Install 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 Serverinstall 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.
Homelab MCP Server
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.
Key Features
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
Quick Start
# Install uv (ultra-fast Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Clone and run
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.
Documentation
Guide | Description |
From zero to first tool call | |
All tools with arguments and examples | |
Environment variables and CLI options | |
Claude Desktop integration guide |
How It Works
Setup -- The server generates an SSH key pair on first run (
~/.ssh/mcp_admin_rsa)Onboard a host -- Use
setup_mcp_adminto create a managed user on the target systemVerify -- Use
verify_mcp_adminto confirm passwordless SSH accessManage -- 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.
MCP Client Configuration
{
"mcpServers": {
"homelab": {
"command": "uv",
"args": ["run", "python", "run_server.py"],
"cwd": "/path/to/homelab_mcp"
}
}
}Development
# 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.
Project Structure
src/homelab_mcp/
server.py # MCP server with JSON-RPC protocol
tool_schemas/ # Tool definitions (7 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
service_templates/ # YAML service definitions
tests/ # Unit and integration tests
docs/ # Full documentationAcknowledgments
Proxmox community script integration powered by community-scripts/ProxmoxVE (MIT License).
Contributing
Fork the repository
Create a feature branch
Write tests for new functionality
Ensure all tests pass
Submit a pull request
License
MIT License -- see LICENSE file for details.
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.