homelab-mcp

MCP server that gives AI assistants full control of a Proxmox homelab — manage VMs and containers, deploy Docker projects, monitor services, control the media stack, and check storage health, all from conversation.

65+ tools across 17 domains. Modular architecture designed for AI-assisted extensibility.

AI Setup

No manual config needed. The server includes an AI-native setup wizard. Just connect it to your MCP client and say:

"Set up my homelab" or "Configure the MCP server"

The setup wizard scans your configuration, guides you through each setting interactively, saves your answers, and verifies connectivity — all through conversation. Credentials are never exposed to the AI; the wizard masks passwords, API keys, and tokens before returning any results.

Quick start

Prerequisites

• Node.js 20+
• A Proxmox VE host reachable over the network
• A devbox (any SSH-accessible Linux host running Docker)
• (Optional) Media services: Plex, Radarr, Sonarr, SABnzbd, Overseerr, Prowlarr
• (Optional) Monitoring: Prometheus, Grafana, Uptime Kuma

Install

From npm (recommended):

npm install -g homelab-mcp
# Or locally in your project:
npm install homelab-mcp

From source (for contributors):

git clone https://github.com/Nainounen/homelab-mcp.git
cd homelab-mcp
npm install
npm run build

Docker (optional)

A Dockerfile is provided for containerized deployments:

npm run build
cp .env.example .env   # edit with your credentials
docker compose up -d

For most users, running directly with Node.js (no Docker) is simpler — the MCP server communicates over stdio.

Connect to your MCP client

Add to your MCP client's config file. For Claude Code, that's ~/.claude/claude_mcp_config.json:

{
  "mcpServers": {
    "homelab": {
      "command": "npx",
      "args": ["homelab-mcp"],
      "cwd": "/path/to/your/homelab-config"
    }
  }
}

Place your .env file in the cwd directory (copy .env.example from this repo as a starting point). No secrets go in the MCP config — the server loads .env from its working directory.

Then just say "set up my homelab" — the AI-native setup wizard will guide you through the rest.

Configuration

All settings live in .env. See .env.example for the full template. The server starts with the services you configure — any service whose env vars are missing is skipped with a warning.

Required (server won't start without these)

Optional (skipped with a warning if missing)

Security settings

Tuning

Tools reference

Infrastructure

Devbox & Docker

Media — download & library

Media — Plex & requests

Media — operational

Monitoring & observability

Storage, network & DNS

Updates, notifications & meta

Architecture

src/
├── {service}.ts          # Layer 1: HTTP/SSH client factory
├── tools/{service}.ts    # Layer 2: Zod schemas + implementations
├── modules/{service}.ts  # Layer 3: Tool definitions + handler router
├── modules/registry.ts   # Central module registry
└── index.ts              # MCP server entry point

Each integration follows the same three-file pattern. Adding a new service means creating these three files and registering it in the registry. The scaffolding script handles the boilerplate:

npm run new-module -- tautulli

See CONTRIBUTING.md for the full guide.

Security

• Credentials: All secrets live in .env, which is gitignored. Never commit it.
• SSH host keys: Verification is off by default (homelab hosts change keys often). Set SSH_STRICT_HOST_KEY=true to enable it.
• TLS: Proxmox/PBS self-signed certs — verification off by default. Set PROXMOX_TLS_VERIFY=true / PBS_TLS_VERIFY=true if you have trusted certs.
• Command safety: exec tools block destructive commands (rm -rf /, mkfs, shutdown, etc.).
• Error sanitization: Error messages returned to the MCP client are sanitized — full details go to stderr.

See SECURITY.md for details.

License

MIT — see LICENSE.