Which integrations are available for this server?

Allows configuration and management of AdGuard Home DNS filtering and ad blocking. Provides tools to manage Docker containers, run Compose projects, and deploy applications on a devbox. Enables version control operations such as checking status, pulling, viewing log, and cloning repositories. Allows interaction with Grafana API for dashboards and monitoring. Provides tools to manage Plex media server: libraries, search, sessions, watch history, and library scans. Enables querying Prometheus API for metrics and monitoring of infrastructure. Provides full management of Proxmox VE nodes, virtual machines, and LXC containers. Allows monitoring and management of QNAP NAS storage health and services. Provides tools for managing movies in Radarr: search, add, remove, queue monitoring, and path mappings. Provides tools for managing TV series in Sonarr: search, add, remove, queue monitoring, and path mappings. Allows sending notifications and alerts via Telegram bot. Enables monitoring of services via Uptime Kuma API for uptime and status checks.

How do I use homelab-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@homelab-mcp set up my homelab" 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

by Nainounen

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

homelab-mcp

npm version License: MIT Node: >=20

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.

Related MCP server: mcp-homelab

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)

Variable	Description
`PROXMOX_HOST`, `PROXMOX_PORT`, `PROXMOX_USER`, `PROXMOX_NODE`	Proxmox API access
`PROXMOX_PASSWORD` or `PROXMOX_KEY_PATH`	Proxmox auth
`DEVBOX_HOST`, `DEVBOX_USER`	Devbox SSH access
`DEVBOX_PASSWORD` or `DEVBOX_KEY_PATH`	Devbox SSH auth
`RADARR_URL`, `RADARR_API_KEY`	Radarr API
`SONARR_URL`, `SONARR_API_KEY`	Sonarr API
`PROWLARR_URL`, `PROWLARR_API_KEY`	Prowlarr API
`SABNZBD_URL`, `SABNZBD_API_KEY`	SABnzbd API
`OVERSEERR_URL`, `OVERSEERR_API_KEY`	Overseerr API

Optional (skipped with a warning if missing)

Variable	Service
`QNAP_HOST`, `QNAP_USER`, `QNAP_PASSWORD` or `QNAP_KEY_PATH`	QNAP NAS
`PLEX_URL`, `PLEX_TOKEN`	Plex
`TAUTULLI_URL`, `TAUTULLI_API_KEY`	Tautulli analytics
`BAZARR_URL`, `BAZARR_API_KEY`	Bazarr subtitles
`ADGUARD_URL`, `ADGUARD_USER`, `ADGUARD_PASSWORD`	AdGuard Home
`PBS_URL`, `PBS_TOKEN_ID`, `PBS_TOKEN_SECRET`	Proxmox Backup Server
`LIDARR_URL`, `LIDARR_API_KEY`	Lidarr music
`READARR_URL`, `READARR_API_KEY`	Readarr books
`UPTIME_KUMA_URL`, `UPTIME_KUMA_USER`, `UPTIME_KUMA_PASSWORD`	Uptime Kuma
`PROMETHEUS_URL`	Prometheus API
`GRAFANA_URL`, `GRAFANA_TOKEN`	Grafana API
`TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`	Telegram notifications

Security settings

Variable	Default	Description
`SSH_STRICT_HOST_KEY`	`false`	Set to `true` to enable `known_hosts` verification
`PROXMOX_TLS_VERIFY`	`false`	Set to `true` to validate Proxmox TLS certificates
`PBS_TLS_VERIFY`	`false`	Set to `true` to validate PBS TLS certificates

Tuning

Variable	Default	Description
`MAX_OUTPUT_CHARS`	`30000`	Max characters per tool result before truncation (`0` disables)
`HTTP_RETRIES`	`3`	Retries for transient HTTP failures (`0` disables)
`DEVBOX_CMD_TIMEOUT`	`30000`	Devbox SSH command timeout in ms
`PROXMOX_CMD_TIMEOUT`	`60000`	Proxmox SSH command timeout in ms

Tools reference

Infrastructure

Tool	Description
`proxmox_list_nodes`	List Proxmox nodes with CPU, RAM, uptime
`proxmox_list_vms`	List all VMs and LXC containers
`proxmox_start_vm`	Start a VM or container
`proxmox_stop_vm`	Stop a VM or container
`proxmox_restart_vm`	Restart a VM or container
`proxmox_get_metrics`	Detailed metrics for one VM/CT
`proxmox_get_node_metrics`	Node-level CPU, RAM, disk, load
`proxmox_create_ct`	Create a new Debian 12 LXC container
`proxmox_get_logs`	Tail task log for a VM/CT
`proxmox_exec`	Run a shell command on Proxmox host (dangerous commands blocked)

Devbox & Docker

Tool	Description
`devbox_exec`	Run a shell command on the devbox (dangerous commands blocked)
`devbox_read_file`	Read a file (max 100 KB)
`devbox_write_file`	Write a file, auto-creates parent dirs (max 1 MB)
`devbox_list_dir`	List directory contents
`devbox_docker_ps`	Show running Docker containers
`devbox_docker_compose`	Run compose up/down/restart/pull/logs
`devbox_git`	Git status, pull, log, or clone a repo
`devbox_project_deploy`	Deploy: git pull → compose pull → compose up → status
`devbox_project_status`	Health check for a deployed project
`devbox_project_list`	Scan a base path for compose projects

Media — download & library

Tool	Description
`radarr_search_movie`	Search for a movie by title
`radarr_add_movie`	Add a movie and trigger download search
`radarr_list_movies`	List movies with download status (filter/search/limit)
`radarr_remove_movie`	Remove a movie (optionally delete files)
`radarr_get_queue`	Active movie downloads with progress
`radarr_force_search`	Re-search indexers for a movie
`radarr_get_history`	Recent download history
`radarr_check_releases`	Show available releases and rejections
`radarr_clear_queue`	Remove all items from download queue
`radarr_clear_blocklist`	Clear the release blocklist
`radarr_blocklist_release`	Blocklist a bad release and retry
`radarr_list_path_mappings`	List remote path mappings
`radarr_set_path_mapping`	Add/update a path mapping
`sonarr_search_series`	Search for a TV series by title
`sonarr_add_series`	Add a series and trigger download
`sonarr_list_series`	List series with episode progress (filter/search/limit)
`sonarr_remove_series`	Remove a series (optionally delete files)
`sonarr_get_queue`	Active episode downloads with progress
`sonarr_force_search`	Re-search for missing episodes
`sonarr_season_search`	Search for a specific season
`sonarr_check_releases`	Show releases and rejections for a season
`sonarr_blocklist_release`	Blocklist and retry a failed download
`sonarr_clear_queue`	Clear the download queue
`sonarr_clear_blocklist`	Clear the release blocklist
`sonarr_list_path_mappings`	List remote path mappings
`sonarr_set_path_mapping`	Add/update a path mapping
`sabnzbd_get_status`	Download speed, ETA, disk space, queue size
`sabnzbd_list_queue`	Active NZB downloads with progress
`sabnzbd_get_history`	Recent download history
`sabnzbd_pause_queue`	Pause downloads
`sabnzbd_resume_queue`	Resume downloads
`sabnzbd_delete_item`	Delete a queue item by NZO ID
`prowlarr_list_indexers`	List indexers with status
`prowlarr_sync_apps`	Sync indexers to Radarr/Sonarr
`prowlarr_test_indexers`	Test all (or one) indexer
`lidarr_search_artist`	Search for a music artist
`lidarr_add_artist`	Add an artist to Lidarr
`lidarr_list_artists`	List all artists with album counts
`lidarr_remove_artist`	Remove an artist
`lidarr_get_queue`	Active music downloads
`readarr_search_book`	Search for a book
`readarr_add_book`	Add a book to Readarr
`readarr_list_books`	List all books
`readarr_get_queue`	Active book downloads

Media — Plex & requests

Tool	Description
`plex_get_libraries`	List Plex libraries with item counts
`plex_search`	Search across all libraries
`plex_get_sessions`	Who is streaming, what, transcode/direct play
`plex_recently_added`	Recently added movies and episodes
`plex_refresh_library`	Trigger a library scan
`plex_delete_media`	Permanently delete by ratingKey
`plex_get_watch_history`	Recent watch history across users
`seerr_list_requests`	List media requests from family
`seerr_approve_request`	Approve a pending request
`seerr_decline_request`	Decline a request
`seerr_delete_request`	Delete a request
`seerr_stats`	Request statistics
`tautulli_get_activity`	Current Plex streams (Tautulli)
`tautulli_get_history`	Plex watch history (Tautulli)
`tautulli_get_stats`	30-day play stats
`bazarr_status`	Wanted subtitle counts
`bazarr_download_subtitle`	Trigger manual subtitle download

Media — operational

Tool	Description
`media_status`	Running container status and uptime
`media_logs`	Tail logs for a media container
`media_restart`	Restart a media container
`media_dashboard`	All-in-one: Proxmox, containers, downloads, library, storage, GPU
`nvidia_status`	GPU temp, util, VRAM, power
`security_status`	SSH config and Proxmox firewall status

Monitoring & observability

Tool	Description
`prometheus_snapshot`	Quick CPU, RAM, disk, network, container health
`prometheus_query`	Run an arbitrary PromQL query
`prometheus_range_query`	Historical metric trends
`grafana_list_dashboards`	List all dashboards
`grafana_get_dashboard`	Get panel list for a dashboard
`grafana_query_panel`	Query actual data from a panel
`uptime_status`	Monitor up/down status and latency

Storage, network & DNS

Tool	Description
`qnap_status`	QNAP NAS: RAID, drive temps, storage
`qnap_disk_health`	SMART health per drive
`qnap_storage_usage`	Per-share usage and LVM
`qnap_raid_status`	RAID array health check
`pbs_status`	PBS datastore usage
`pbs_list_snapshots`	Recent backup snapshots
`pbs_get_tasks`	Backup/verify/GC task history
`adguard_stats`	DNS query stats and block rate
`adguard_check_host`	Check if a domain is blocked
`adguard_toggle_protection`	Enable/disable DNS filtering
`wol_send`	Wake-on-LAN magic packet
`tailscale_status`	Tailscale peers and status

Updates, notifications & meta

Tool	Description
`container_check_updates`	Check for newer Docker images
`container_update`	Pull + restart a container
`notify_telegram`	Send a message to Telegram
`homelab_health`	Ping all configured services, report reachable/down + latency
`homelab_capabilities`	Start here — lists all available tools
`homelab_setup`	AI-guided setup wizard — configure `.env` through conversation

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.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

gainium-mcpOAuth
io.gainium
MCP server for Gainium — manage trading bots, deals, and balances via AI assistants
Cryptocurrency Finance
22
mcp-veoOAuth
io.github.AceDataCloud
MCP server for Google Veo AI video generation
Multimedia Processing Image & Video Processing Entertainment & Media
23
ZapierOAuth
com.zapier
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
App Automation Workplace & Productivity
2297
mcp-lumaOAuth
io.github.AceDataCloud
MCP server for Luma Dream Machine AI video generation
Multimedia Processing Image & Video Processing
2

Related MCP Servers

mcp-server-proxmox
Virtualization Cloud Platforms
heybearc
A
license
Not graded
quality
C
maintenance
A Model Context Protocol (MCP) server for Proxmox Virtual Environment that enables AI assistants to manage virtual machines, containers, nodes, and resources through natural language interactions.
Updated 3 days ago (2026-09-15 11:06 UTC)
10
3
MIT
mcp-homelab
Virtualization Networking & Infrastructure Shell Access
asvarnon
A
license
Not graded
quality
D
maintenance
An MCP server that gives AI assistants real-time access to your homelab infrastructure. It enables querying node status, managing Docker containers, controlling Proxmox VMs, and inspecting OPNsense firewall state through natural conversation.
Updated 4 months ago (2026-06-02 04:37 UTC)
2
MIT
io.github.AIops-tools/proxmox
Virtualization Command Line
AIops-tools
A
license
A
quality
A
maintenance
AI-powered MCP server for managing Proxmox VE VMs and containers with built-in governance, audit logging, and reversibility.
Updated 16 days ago (2026-09-02 13:44 UTC)
43
2
MIT
proxmox-mcp
Virtualization Cloud Platforms
LeonRLewis
F
license
Not graded
quality
C
maintenance
MCP server for Proxmox VE that enables AI assistants to inspect and manage LXC containers, VMs, snapshots, and resource pools via the Proxmox API.
Updated 3 months ago (2026-06-30 21:52 UTC)
-

homelab-mcp

AI Setup

Quick start

Prerequisites

Install

Docker (optional)

Connect to your MCP client

Configuration

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

Security

License

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

mcp-server-proxmox

mcp-homelab

io.github.AIops-tools/proxmox

proxmox-mcp