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.

Tools cover infrastructure, media automation, monitoring, storage, and network services. The modular architecture lets contributors add integrations without changing the MCP server core.

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_get_command`	Check the status of an asynchronous Radarr command
`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
`radarr_interactive_search`	Search releases with rejection reasons, languages, custom formats, and scores
`radarr_grab_release`	Grab one selected release by GUID and indexer ID
`radarr_manual_import`	Preview and import files from a specified folder
`radarr_list_custom_formats`	List custom formats and profile scores
`radarr_set_custom_format`	Create or update a custom format
`radarr_set_cf_score`	Set a custom format score on a quality profile
`radarr_get_quality_profile`	Inspect a profile and its guarded edit digest
`radarr_create_quality_profile`	Clone a profile template with selected quality and score settings
`radarr_edit_quality_profile`	Update a profile with digest protection
`radarr_delete_quality_profile`	Preview references before removing an unused profile
`radarr_bulk_set_quality_profile`	Assign a profile to a selected batch of movies
`radarr_remove_queue_item`	Dismiss one stale queue row without deleting the download
`radarr_remove_queue_items`	Preview and dismiss an explicit batch of queue rows
`radarr_blocklist_releases`	Preview and blocklist an explicit batch of tracked queue releases
`radarr_inspect_replacement`	Inspect a downloaded replacement candidate
`radarr_plan_downgrade`	Find smaller release candidates and report expected savings
`radarr_download_replacement`	Preview or download a selected smaller release
`radarr_import_replacement`	Preview or import a selected replacement file
`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_get_command`	Check the status of an asynchronous Sonarr command
`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
`sonarr_interactive_search`	Search releases with rejection reasons, languages, custom formats, and scores
`sonarr_grab_release`	Grab one selected release by GUID and indexer ID
`sonarr_manual_import`	Preview and import files from a specified folder
`sonarr_list_custom_formats`	List custom formats and profile scores
`sonarr_set_custom_format`	Create or update a custom format
`sonarr_set_cf_score`	Set a custom format score on a quality profile
`sonarr_get_quality_profile`	Inspect a profile and its guarded edit digest
`sonarr_create_quality_profile`	Clone a profile template with selected quality and score settings
`sonarr_edit_quality_profile`	Update a profile with digest protection
`sonarr_delete_quality_profile`	Preview references before removing an unused profile
`sonarr_remove_queue_item`	Dismiss one stale queue row without deleting the download
`sonarr_remove_queue_items`	Preview and dismiss an explicit batch of queue rows
`sonarr_blocklist_releases`	Preview and blocklist an explicit batch of tracked queue releases
`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_get_warnings`	Read active SABnzbd warnings and errors
`sabnzbd_get_job`	Inspect a specific NZO ID in the queue or history, including failures and post-processing
`sabnzbd_pause_queue`	Pause downloads
`sabnzbd_resume_queue`	Resume downloads
`sabnzbd_delete_item`	Delete a queue item by NZO ID
`sabnzbd_delete_queue_items`	Preview and delete selected queue jobs by NZO ID and expected name
`sabnzbd_delete_history`	Preview and permanently delete selected terminal history entries
`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

Bulk queue and history tools accept 1 to 200 explicit items. SABnzbd selections support both legacy SABnzbd_nzo_ IDs and UUID IDs; broad selectors such as all and failed are rejected. Preview first, then pass the returned batch_digest as expected_batch_digest with preview_only: false. The restricted media server requests one native human approval for that batch and rechecks it before applying. Files and replacement searches are preserved or disabled by default. Sonarr and Radarr batches must include every queue row sharing a selected download ID; blocklisting requires a currently tracked release. SABnzbd history deletion skips Archive and accepts only Completed or Failed entries. Results report whether each row disappeared; this does not establish media availability or confirm file deletion. After an uncertain write, inspect current state before retrying.

Media — Plex & requests

Tool	Description
`plex_get_metadata`	Inspect one movie or show's current metadata identity and files
`plex_get_matches`	Find candidate metadata matches for one movie or show
`plex_fix_match`	Preview and approve a guarded metadata rematch
`plex_get_libraries`	List Plex libraries with item counts
`plex_list_shares`	List pending and accepted library shares
`plex_invite_user`	Preview an invitation to selected libraries
`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_get_request`	Inspect request status, availability, seasons, and linked Arr IDs
`seerr_retry_request`	Preview or retry a failed request
`seerr_get_quality_profile_settings`	Inspect linked Arr servers and Seerr default profiles
`seerr_set_quality_profile`	Change the quality profile used for future requests
`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`	Preview or download a subtitle for one movie or episode
`bazarr_search_wanted_movies`	Start Bazarr's wanted movie search after preview
`bazarr_search_wanted_episodes`	Start Bazarr's wanted episode search after preview
`bazarr_get_settings`	Inspect settings with secrets redacted
`bazarr_update_settings`	Preview and patch selected settings
`bazarr_set_enabled_languages`	Preview and replace enabled subtitle languages
`bazarr_set_language_profiles`	Preview and replace the language profile list
`bazarr_get_system_health`	Inspect Bazarr health
`bazarr_get_system_tasks`	Inspect scheduled system tasks
`bazarr_get_system_jobs`	Inspect background job progress
`bazarr_get_providers`	Inspect subtitle provider configuration and status
`bazarr_get_movies_wanted`	List movies missing subtitles
`bazarr_get_episodes_wanted`	List episodes missing subtitles

Bazarr also exposes tools generated from its API schema for subtitle history, blacklist, files, providers, languages, backups, logs, and system tasks. Write operations preview by default. For write tools that return an expected_hash, pass that value back to apply the change against the state you reviewed.

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.

Public web research for Hermes

The separate dist/web.js MCP entrypoint exposes web_search and web_fetch using DeepSeek's official Search API and a guarded public-page reader. It loads only /etc/homelab-mcp/web.env, runs as homelab-web, and has no media credentials. Search accepts up to 128 characters and 10 results. Fetch accepts public HTTPS URLs on port 443, rejects private/reserved DNS and IP addresses, and returns up to 20,000 characters of untrusted text. Page requests pin the validated public IP, check each redirect, and send no credentials or cookies. The search credential is sent only to the fixed DeepSeek search endpoint. The web entrypoint requires Node.js 22.13 or newer for its built-in SQLite quota store.

Both tools share a persistent SQLite daily limit of 100 attempts, with at least one second between requests. WEB_DAILY_LIMIT configures the cap (1 to 1,000); WEB_STATE_DIR must be private and owned by the service user. WEB_BLOCKED_DOMAINS adds comma-separated domain exclusions. Credential-like queries and URLs are rejected before submission, but agents must still keep private conversations and internal diagnostics out of public search requests. Retrieved content is evidence, never authorization to run commands or change homelab services.

For Plex matching, use plex_search to find a rating key, inspect plex_get_metadata, and query plex_get_matches. Preview plex_fix_match with an exact candidate GUID, then pass the returned match_digest as expected_match_digest with preview_only: false after native approval. The item and candidate are checked again before applying. Show matches can refresh child metadata; no media file operations are submitted. Re-read current metadata after uncertain results before retrying.

On Guardian, deploy the compiled artifacts and run scripts/install-guardian-web-search.py with Hermes's Python environment to configure the isolated account, reuse the existing DeepSeek credential without printing it, and register the tools for Telegram. The installer creates configuration and instruction backups. Restart hermes-gateway after verification.

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

ActivityMaintained

ResponsivenessNo issues

Resources

Related MCP Connectors

Server4Agent A
com.server4agent
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
App Automation Cloud Platforms Developer Tools
343
https://mcp.server4agent.com
gainium-mcpOAuth
io.gainium
MCP server for Gainium — manage trading bots, deals, and balances via AI assistants
Cryptocurrency Finance
22
https://mcp.gainium.io/mcp
mcp-veoOAuth
io.github.AceDataCloud
MCP server for Google Veo AI video generation
Multimedia Processing Image & Video Processing Entertainment & Media
23
https://veo.mcp.acedata.cloud/mcp
ZapierOAuth
com.zapier
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
App Automation Workplace & Productivity
2297
https://mcp.zapier.com/api/v1/connect

Related MCP Servers

mcp-server-proxmox
Virtualization Cloud Platforms
heybearc
A
license
B
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 6 days ago (2026-10-26 12:16 UTC)
10
4
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 5 months ago (2026-06-02 04:37 UTC)
28 PyPI
2
MIT
proxmox-mcp
Virtualization Cloud Platforms
LeonRLewis
F
license
Not graded
quality
D
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 4 months ago (2026-06-30 21:52 UTC)
-
MCP Hub
Shell Access Virtualization Cloud Platforms
wnx82
A
license
Not graded
quality
B
maintenance
A single MCP server that gives an AI assistant comprehensive access to manage a homelab, including SSH, Docker, Proxmox, Synology, Cloudflare, and more, with 85 tools and a centralized configuration.
Updated 2 months ago (2026-08-24 11:15 UTC)
MIT

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

Public web research for Hermes

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

mcp-server-proxmox

mcp-homelab

proxmox-mcp

MCP Hub