Homelab MCP Server
About
Manage and monitor homelab systems via SSH.
Details
- Author
- washyu
- Categories
- Productivity, Other, Infrastructure
Jump to
Setup
Install Homelab MCP Server in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/washyu/mcp_python_server
Follow the installation instructions in the repository README, then restart your MCP client.
Manage and monitor homelab systems via SSH.
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
# 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.py
For the full walkthrough (environment variables, MCP client configuration, first tool call), see theSetup Guide.
- Setup-- The server generates an SSH key pair on first run (~/.ssh/mcp_admin_rsa)
- Onboard a host-- Usesetup_mcp_adminto create a managed user on the target system
- Verify-- Useverify_mcp_adminto 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.10
The CLI provides full CRUD over credentials:add(create/update — upsert),list(read),remove(delete). There is no separateupdatesubcommand — re-runningaddreplaces 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.
SeeCredentials CLI referencefor full documentation.
{ "mcpServers": { "homelab": { "command": "uvx", "args": ["homelab-mcp"] } } }
{ "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/
SeeDEPLOYMENT.mdfor 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 documentation
Proxmox community script integration powered bycommunity-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.
Model Context Protocol server for secure AsusWRT router administration via SSH. Provides 42+ read-only monitoring tools and guarded mutation tools for managing AsusWRT/Merlin routers.
AI-native network automation for MikroTik RouterOS. MikroMCP exposes RouterOS as a typed, auditable Model Context Protocol server so Claude, Cursor, Codex, and other MCP clients can inspect, diagnose, and safely operate MikroTik routers in natural language.
Read-only SSH server diagnostics: 38-command whitelist, secret-redacted.
MCP servers for managing homelab infrastructure through Claude Desktop. Monitor Docker/Podman containers, Ollama AI models, Pi-hole DNS, Unifi networks, and Ansible inventory.
Provides JMX monitoring and management capabilities for AI assistants. Requires Java 17+.
The nginx of MCP — drop-in resilience middleware for any MCP server.
An MCP server that provides system information, such as CPU and memory usage.
Connect to Netdata MCP using Claude desktop
MCP server for interacting with network devices (switches, routers) over SSH. Supports Arista EOS, Cisco NX-OS, and Cisco IOS/IOS-XE. Exposes network device operations as tools for use with Claude Code and Claude Desktop (and other MCP clients)
A SSH MCP Server written in python. Which builds upon a sophisticated tools and permission layer. Including Skills, Docker and Systemctl toolset and some runbooks.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
