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 "Install 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 Related Servers Score Discussions

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: HA Vibecode Agent

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

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 all movies with download status
`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 all series with episode progress
`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 installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

0dRelease cycle

3Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Nainounen/homelab-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server