🏠 Homelab MCP Server

AI-Powered VM Infrastructure Management with Advanced Service Installation Framework

A comprehensive Model Context Protocol (MCP) server that enables AI assistants to manage, deploy, and monitor homelab infrastructure through automated service installation, Terraform state management, and VM operations.

🚀 Quick Start

# Install uv (ultra-fast Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and run (takes 3 seconds!)
git clone https://github.com/washyu/homelab_mcp.git
cd homelab_mcp
uv sync && uv run python run_server.py

✨ Key Features

🤖 AI-Driven Service Installation

• 49 MCP Tools for complete infrastructure lifecycle management
• Service Templates for Jellyfin, Pi-hole, Ollama, Home Assistant, and more
• Proxmox Integration with full API access and 400+ community scripts for discovery
• Terraform Support with state management and clean resource tracking
• Automated Deployment with requirement validation and health checking
• One-Command Installation: "Install Pi-hole on my homelab server"

🔧 VM Infrastructure Management

• SSH-based Discovery: Gather comprehensive hardware/software information from any system
• Automated User Setup: Configure mcp_admin with passwordless access and selective permissions
• Container Operations: Deploy, manage, and remove Docker/LXD containers with state tracking
• Network Mapping: Intelligent device discovery, topology analysis, and change tracking

🏗️ Enterprise-Grade Infrastructure as Code

• Terraform Integration: Full state management with local/S3 backends
• Idempotent Deployments: Safe to run multiple times with automatic drift detection
• Clean Resource Management: Proper destroy workflows that remove only what was created
• Multi-Backend Support: Local files, S3-compatible storage, Consul/etcd for HA

⚡ Ultra-Fast Development

• uv Package Manager: 600x faster dependency installation (0.07s vs 45s with pip)
• Reproducible Builds: Lock files ensure consistent deployments across environments
• Zero Configuration: Dependencies and virtual environments handled automatically

🛠 Available Tools (41 Total)

🛠️ Service Management Tools (4)

list_available_services

List all available service templates for homelab deployment.

install_service

Deploy services with automated configuration and validation.

plan_terraform_service

Generate Terraform execution plans to preview infrastructure changes without applying them.

destroy_terraform_service

Cleanly destroy Terraform-managed services and remove all associated resources.

📦 Featured Services Available

Ollama - Local LLM Server

• Self-hosted LLM deployment for privacy-focused AI applications
• Model support for tinyllama, phi, mistral, and other open-source models
• API integration for chat interfaces and custom applications
• Resource-efficient operation suitable for homelab environments

Home Assistant - Smart Home Automation

• GPIO integration for Raspberry Pi sensors and control
• Zigbee/Z-Wave hub capabilities with USB dongles
• Energy monitoring and automation rules
• Mobile app integration for remote access

SSH & Admin Tools (5)

start_interactive_shell

Start an interactive web-based shell session on a remote system:

• Full TTY support with xterm.js browser-based terminal
• Perfect for interactive scripts like Proxmox community scripts that require user input
• Persistent sessions with automatic cleanup after 30 minutes of inactivity
• Secure access through API key authentication
• Returns a URL to open the shell in your browser

Example use case: Run Proxmox community scripts interactively, navigate the filesystem, edit files, or debug issues with a full terminal experience.

Note: Uses registered SSH credentials or accepts username/password. Sessions are isolated and automatically cleaned up.

ssh_discover

SSH into a remote system and gather comprehensive system information including:

• CPU details (model, cores, architecture)
• Memory usage (total, available, used)
• Storage information (disk usage, mount points)
• Network interfaces (IPs, MAC addresses, link status)
• Hardware discovery: USB devices, PCI devices (network cards, GPUs), block devices (drives, partitions)
• Operating system information and uptime

Note: When using username mcp_admin, the tool automatically uses the MCP's SSH key if available. No password is required after running setup_mcp_admin on the target system.

setup_mcp_admin

SSH into a remote system using admin credentials and set up the mcp_admin user with:

• User creation (if not exists)
• Sudo group membership with passwordless access
• SSH key authentication (using MCP's auto-generated key)
• Selective group permissions (only adds groups for installed services like docker, lxd)

Parameters:

• hostname: Target system IP or hostname
• username: Admin username with sudo access
• password: Admin password
• force_update_key (optional, default: true): Force update SSH key even if mcp_admin already has other keys

verify_mcp_admin

Verify SSH key access to the mcp_admin account on a remote system:

• Tests SSH key authentication
• Verifies sudo privileges
• Returns connection status

Network Discovery Tools (6)

discover_and_map

Discover a device via SSH and store it in the network site map database.

bulk_discover_and_map

Discover multiple devices via SSH and store them in the network site map database.

get_network_sitemap

Get all discovered devices from the network site map database.

analyze_network_topology

Analyze the network topology and provide insights about the discovered devices.

suggest_deployments

Suggest optimal deployment locations based on current network topology and device capabilities.

get_device_changes

Get change history for a specific device.

Infrastructure CRUD Tools (7)

deploy_infrastructure

Deploy new infrastructure based on AI recommendations or user specifications:

• Deploy Docker containers, LXD containers, or systemd services
• Configure networking, storage, and environment variables
• Validate deployment plans before execution

update_device_config

Update configuration of an existing device:

• Modify service configurations
• Update network settings
• Change security configurations
• Adjust resource allocations

decommission_device

Safely remove a device from the network infrastructure:

• Analyze dependencies and critical services
• Execute migration plans to move services
• Graceful shutdown and removal

scale_services

Scale services up or down based on resource analysis:

• Horizontal scaling of containers/VMs
• Resource allocation adjustments
• Load balancing configuration

validate_infrastructure_changes

Validate infrastructure changes before applying them:

• Basic, comprehensive, and simulation validation levels
• Dependency checking
• Risk assessment

create_infrastructure_backup

Create a backup of current infrastructure state:

• Full or partial backups
• Device-specific backups
• Configuration and data backup options

rollback_infrastructure_changes

Rollback recent infrastructure changes:

• Restore from backups
• Selective rollback capabilities
• Validation before rollback

VM Management Tools (6)

deploy_vm

Deploy a new VM/container on a specific device:

• Support for Docker containers and LXD VMs
• Configurable images, ports, volumes, environment variables
• Platform-agnostic deployment

control_vm

Control VM state (start, stop, restart):

• Manage VM lifecycle
• Support for both Docker and LXD platforms
• Real-time status updates

get_vm_status

Get detailed status of a specific VM:

• Container/VM health information
• Resource usage statistics
• Network and storage details

list_vms

List all VMs/containers on a device:

• Cross-platform inventory
• Status and configuration overview
• Multi-device support

get_vm_logs

Get logs from a specific VM/container:

• Configurable log line limits
• Support for Docker and LXD logs
• Real-time log streaming

remove_vm

Remove a VM/container from a device:

• Graceful or forced removal
• Data preservation options
• Cleanup of associated resources

Proxmox Community Scripts Integration (2)

Discover and get information about 400+ community-maintained Proxmox installation scripts:

search_proxmox_scripts

Search the Proxmox community scripts repository:

• Search by keyword (docker, homeassistant, pihole, etc.)
• Filter by category (containers, VMs, installers)
• Optional metadata fetching for resource requirements
• Access to 400+ community-maintained installation scripts

get_proxmox_script_info

Get detailed information about a specific script:

• CPU, RAM, and disk requirements
• OS and version specifications
• Tags and categorization
• Script preview and download URL with command to run

Note: Script execution is not automated because these scripts are interactive and require user input during installation. The AI can help you find the right script and show its requirements, then you run it manually from the Proxmox web shell where you can respond to prompts.

Scripts provided by: community-scripts/ProxmoxVE (MIT License)

Proxmox API Integration (8)

Direct Proxmox API access for comprehensive cluster management:

list_proxmox_resources

List all cluster resources:

• VMs, LXC containers, nodes, storage, pools
• Filter by resource type
• Real-time status and metrics
• Uses PROXMOX_HOST from environment

get_proxmox_node_status

Get detailed node information:

• CPU usage and specifications
• Memory usage and capacity
• Uptime and load averages
• Disk and network statistics

get_proxmox_vm_status

Get specific VM/container status:

• Resource usage (CPU, memory, disk, network)
• Configuration details
• Current state (running, stopped, suspended)
• Supports both QEMU VMs and LXC containers

manage_proxmox_vm

Control VM/container lifecycle:

• Actions: start, stop, shutdown, restart, suspend, resume
• Graceful shutdowns vs forced stops
• Real-time operation status

create_proxmox_lxc

Create new LXC containers:

• Choose from available OS templates
• Configure CPU cores, RAM, and disk
• Network configuration
• Storage selection

create_proxmox_vm

Create new QEMU VMs:

• ISO or template-based deployment
• Hardware configuration (CPU, RAM, disk, network)
• Boot order and BIOS settings
• SCSI/VirtIO storage options

clone_proxmox_vm

Clone existing VMs or containers:

• Full or linked clones
• New VMID assignment
• Name and description customization
• Fast template-based deployments

delete_proxmox_vm

Remove VMs or containers:

• Clean resource deallocation
• Confirmation safeguards
• Disk cleanup options

Authentication: Supports both API tokens (no expiration) and username/password (2-hour sessions). Configure via environment variables or pass credentials per-call.

🏗️ Terraform vs SSH Commands

Why Terraform Integration Matters

Aspect	SSH Commands	Terraform	Benefit
State Tracking	❌ Manual	✅ Automatic	Know exactly what was created
Idempotency	❌ Can break	✅ Safe reruns	Run deployments multiple times
Clean Removal	❌ Orphaned resources	✅ Complete cleanup	Remove only what Terraform created
Drift Detection	❌ Manual checks	✅ Automatic	Detect manual changes
Rollback	❌ Manual process	✅ State-based	Revert to previous configurations

Deployment Methods Available

# Docker Compose (fast, simple)
"Install Pi-hole using Docker Compose"

# Terraform (enterprise-grade, state-managed)
"Install Pi-hole using Terraform with state management"

# Both methods support the same services

🎭 Ansible Configuration Management

Why Ansible for Multi-Service Deployments

Perfect for deploying multi-service homelab stacks with complex dependencies:

Capability	Docker Compose	Terraform	Ansible	Best For
Single Host Services	✅ Excellent	✅ Good	✅ Good	Simple deployments
Multi-Host Orchestration	❌ Limited	✅ Infrastructure	✅ Configuration	Complex setups
System Configuration	❌ Container only	❌ Limited	✅ Full control	OS-level setup
Service Dependencies	✅ Basic	✅ Resource deps	✅ Cross-service config	Interconnected services
Idempotent Operations	✅ Yes	✅ Yes	✅ Yes	Safe re-runs

Available Ansible Services

# Full AI homelab stack (MCP + Ollama + Web UI + Nginx)
"Install ai_homelab_stack_ansible on my Pi for complete AI setup"

# Individual service with system integration
"Install ollama_ansible on my server for system-level LLM hosting"

Ansible Tools

• check_ansible_service - Verify Ansible deployment status
• run_ansible_playbook - Execute playbooks with tags/variables

Example: Complete AI Stack Deployment

# One command deploys entire stack:
# ✅ MCP Server as systemd service
# ✅ Ollama LLM server
# ✅ Web UI with pre-configured API endpoints
# ✅ Nginx reverse proxy with SSL ready
# ✅ Firewall configuration
# ✅ Health checks and monitoring

"Install ai_homelab_stack_ansible on my homelab server"

Installation

Quick Start (Recommended)

# Install uv (ultra-fast Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and run (takes 3 seconds!)
git clone https://github.com/washyu/homelab_mcp.git
cd homelab_mcp
uv sync && uv run python run_server.py

Traditional pip Installation

# Clone the repository
git clone https://github.com/washyu/homelab_mcp.git
cd homelab_mcp

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies (much slower than uv)
pip install -e .

For Development

# Install with development dependencies
uv sync --group dev

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/homelab_mcp

Usage

Running the Server

python run_server.py

The server communicates via stdio (stdin/stdout) using the MCP protocol.

SSH Key Management

The MCP server automatically generates an SSH key pair on first initialization:

• Private key: ~/.ssh/mcp_admin_rsa
• Public key: ~/.ssh/mcp_admin_rsa.pub

This key is used for:

1. Authenticating as mcp_admin on remote systems after setup
2. Enabling passwordless SSH access for system management
3. Automatic authentication when using ssh_discover with username mcp_admin

Testing with JSON-RPC

You can test the server by sending JSON-RPC requests:

# List available tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | python run_server.py

# Discover a system via SSH (with password)
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"ssh_discover","arguments":{"hostname":"192.168.1.100","username":"user","password":"pass"}}}' | python run_server.py

# Discover using mcp_admin (no password needed after setup)
echo '{"jsonrpc":"2.0","id":3b,"method":"tools/call","params":{"name":"ssh_discover","arguments":{"hostname":"192.168.1.100","username":"mcp_admin"}}}' | python run_server.py

# Setup mcp_admin on a remote system
echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"setup_mcp_admin","arguments":{"hostname":"192.168.1.100","username":"admin","password":"adminpass"}}}' | python run_server.py

# Verify mcp_admin access
echo '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"verify_mcp_admin","arguments":{"hostname":"192.168.1.100"}}}' | python run_server.py

# Use ssh_discover with mcp_admin (no password needed after setup)
echo '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"ssh_discover","arguments":{"hostname":"192.168.1.100","username":"mcp_admin"}}}' | python run_server.py

Integration with AI Assistants

This server is designed to work with AI assistants that support the Model Context Protocol.

🚀 For detailed Claude setup instructions, see CLAUDE_SETUP.md

Recommended configuration for Claude Desktop (using uv):

{
  "mcpServers": {
    "homelab": {
      "command": "/opt/homebrew/bin/uv",
      "args": ["run", "python", "/Users/your-username/workspace/homelab_mcp/run_server.py"],
      "cwd": "/Users/your-username/workspace/homelab_mcp"
    }
  }
}

Alternative configuration (traditional Python):

{
  "mcpServers": {
    "homelab": {
      "command": "python3",
      "args": ["/path/to/your/homelab_mcp/run_server.py"],
      "env": {
        "PYTHONPATH": "/path/to/your/homelab_mcp/src"
      }
    }
  }
}

Place this in:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

Typical Workflow

1. Initial Setup: The MCP automatically generates its SSH key on first run
2. Configure Remote System: Use setup_mcp_admin with admin credentials to:
   • Create the mcp_admin user on the target system
   • Install the MCP's public key for authentication
   • Grant sudo privileges
3. Verify Access: Use verify_mcp_admin to confirm setup was successful
4. Manage Systems: Use ssh_discover with username mcp_admin for passwordless access

Example workflow:

# 1. Setup mcp_admin on a new system
{"method":"tools/call","params":{"name":"setup_mcp_admin","arguments":{"hostname":"192.168.1.50","username":"pi","password":"raspberry"}}}

# 2. Verify the setup worked
{"method":"tools/call","params":{"name":"verify_mcp_admin","arguments":{"hostname":"192.168.1.50"}}}

# 3. Now discover system info without needing passwords
{"method":"tools/call","params":{"name":"ssh_discover","arguments":{"hostname":"192.168.1.50","username":"mcp_admin"}}}

Handling Key Updates

If the mcp_admin user already exists but has a different SSH key, the setup_mcp_admin tool will automatically update it by default. You can control this behavior:

# Force update the SSH key (default behavior)
{"method":"tools/call","params":{"name":"setup_mcp_admin","arguments":{"hostname":"192.168.1.50","username":"pi","password":"raspberry","force_update_key":true}}}

# Keep existing keys (only add if no MCP key exists)
{"method":"tools/call","params":{"name":"setup_mcp_admin","arguments":{"hostname":"192.168.1.50","username":"pi","password":"raspberry","force_update_key":false}}}

When force_update_key is true (default), the tool will:

1. Remove any existing MCP keys (identified by the mcp_admin@ comment)
2. Add the current MCP's public key
3. Preserve any other SSH keys the user might have

🎯 Example Use Cases

Homelab Service Deployment

# 1. Deploy local LLM server
"Install Ollama on my server for hosting Mistral 7B locally"

# 2. Set up smart home automation
"Install Home Assistant on my Pi for smart home control"

# 3. Create network-wide ad blocking
"Install Pi-hole on my Pi for ad blocking with DNS configuration"

# 4. Deploy media server
"Install Jellyfin on my server for media streaming"

Enterprise Infrastructure Management

# 1. Discover and map network infrastructure
"Discover all devices on my network and create a topology map"

# 2. Deploy enterprise storage
"Install TrueNAS on my storage server with ZFS optimization"

# 3. Set up Kubernetes cluster
"Deploy K3s on my cluster nodes for container orchestration"

# 4. Use Terraform for state management
"Install Pi-hole using Terraform with state tracking and backup"

Hardware Discovery and Optimization

# 1. Comprehensive hardware audit
"Discover my server's hardware including USB devices and network cards"

# 2. Storage analysis
"Analyze disk usage and performance across my homelab servers"

# 3. Network device identification
"Show me all network adapters and their capabilities on my devices"

Development and Testing

# 1. Container development platform
"Deploy development containers with persistent storage"

# 2. Service monitoring and debugging
"Check service status and show logs for troubleshooting"

# 3. Infrastructure as code testing
"Plan Terraform changes before applying to production"

Development

Project Structure

homelab_mcp/
├── src/
│   └── homelab_mcp/
│       ├── __init__.py
│       ├── server.py           # Main MCP server with JSON-RPC protocol
│       ├── tools.py            # Tool registry and execution (49 tools)
│       ├── ssh_tools.py        # SSH discovery with 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 database for device tracking
│       └── service_templates/  # YAML service definitions
│           ├── ollama.yaml         # Local LLM server
│           ├── homeassistant.yaml  # Smart home automation
│           ├── pihole.yaml         # Network-wide ad blocking
│           ├── pihole_terraform.yaml # Terraform-managed Pi-hole
│           ├── jellyfin.yaml       # Media server
│           ├── k3s.yaml           # Lightweight Kubernetes
│           └── truenas.yaml       # Network-attached storage
├── tests/
│   ├── integration/       # Integration tests with Docker
│   ├── test_*.py         # Unit tests for all components
│   └── conftest.py       # Test fixtures and setup
├── scripts/
│   └── run-integration-tests.sh  # Test automation
├── docs/
│   ├── CLAUDE_SETUP.md       # Claude Desktop integration guide
│   ├── DEPLOYMENT.md         # uv deployment guide
│   ├── QUALITY_ASSURANCE.md  # Quality assurance documentation
│   └── WORKFLOWS.md          # Development workflows
├── pyproject.toml        # uv project configuration
├── uv.lock              # Dependency lock file
└── run_server.py        # Entry point with debug diagnostics

Running Tests

Unit Tests

# Run all unit tests (fast, no Docker required)
pytest tests/ -m "not integration"

# Run with coverage
pytest tests/ -m "not integration" --cov=src/homelab_mcp

# Run specific test file
pytest tests/test_server.py

Integration Tests

# Prerequisites: Docker and docker-compose must be installed and running

# Run integration tests (requires Docker)
./scripts/run-integration-tests.sh

# Or run manually
pytest tests/integration/ -m integration -v

# Run specific integration test
pytest tests/integration/test_ssh_integration.py::TestSSHIntegration::test_full_mcp_admin_setup_workflow -v

All Tests

# Run all tests (unit + integration)
pytest

# Note: Integration tests will be skipped if Docker is not available

Adding New Tools

1. Define the tool schema in src/homelab_mcp/tools.py:

TOOLS["new_tool"] = {
    "description": "Tool description",
    "inputSchema": {
        "type": "object",
        "properties": {
            # Define parameters
        },
        "required": []
    }
}

2. Implement the tool logic in the appropriate module

3. Add the execution case in execute_tool() function

4. Write tests for the new tool

Acknowledgments

Proxmox Community Scripts

This project integrates with the excellent community-scripts/ProxmoxVE repository to help users discover installation scripts for Proxmox VE containers and virtual machines.

Attribution:

• Project: Proxmox VE Helper-Scripts
• Repository: https://github.com/community-scripts/ProxmoxVE
• Author: tteck (tteckster) and community contributors
• License: MIT License
• Website: https://helper-scripts.com

The Proxmox script integration tools (search_proxmox_scripts, get_proxmox_script_info) provide discovery and information about scripts from their repository. All scripts are copyright of their respective authors and distributed under the MIT License.

What we provide:

• Script discovery and search functionality
• Metadata parsing (CPU, RAM, disk requirements)
• Download URLs and installation commands

We do not:

• Host or redistribute their scripts
• Modify their script content
• Claim authorship of their work
• Automate script execution (scripts are interactive and require user input)

All script information is fetched directly from their GitHub repository at runtime, ensuring you always get the latest versions with all community updates and security fixes.

Thank you to tteck and all contributors for maintaining this invaluable resource for the Proxmox community!

License

MIT License - see LICENSE file for details

Contributing

1. Fork the repository
2. Create a feature branch
3. Write tests for new functionality
4. Ensure all tests pass
5. Submit a pull request