home / mcp / homelab mcp server

Homelab MCP Server

Modular MCP server for homelab service management, providing unified access to multiple services and health checks.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "havartibard-homelab-mcp": {
      "url": "http://192.168.1.100:6971/mcp"
    }
  }
}

Homelab MCP is a modular server that unifies access to multiple homelab services through a single MCP API. You can enable only the services you need, monitor health from one endpoint, and deploy it easily with Docker, on Unraid, Proxmox, or Kubernetes.

How to use

Connect your MCP client to the Homelab MCP server to manage and monitor your services from a single interface. You can use the remote MCP endpoint to integrate your tools, or run the server locally for development and testing.

Common workflows include running health checks across all enabled services, listing configured services and their status, and invoking per-service tools to manage specific resources such as proxies, DNS, monitoring, Docker endpoints, UPS status, or network devices.

If you run the server locally for development, use the development command to start the runtime and then connect your client to the local endpoint. For production use, prefer the containerized deployment options and point clients at the appropriate MCP URL.

How to install

Prerequisites you need before installation: Python and pip for development, Docker for containerized deployment, and git for cloning repositories.

Step-by-step installation and setup you can follow:

# 1. Clone the repository
git clone https://github.com/HavartiBard/homelab-mcp.git
cd homelab-mcp

# 2. Prepare configuration
cp config.example.yaml config.yaml
# Edit config.yaml with your service URLs and credentials

Step to run in development mode (local runtime): you will use Python to start the MCP server.

# Install dependencies
pip install -e .

# Run server locally (development)
python -m homelab_mcp.main

Production or containerized deployment options are provided to simplify deployment in common environments.

# Docker Compose (recommended)
docker compose up -d

Unraid deployment and Kubernetes deployment are also supported with explicit steps in their respective sections.

Additional content

Configuration is done in the config.yaml file. The example shows how to enable services and provide credentials. You can enable and configure each service individually.

server:
  host: "0.0.0.0"
  port: 6971
  transport: "streamable-http"

services:
  nginx_proxy_manager:
    enabled: true
    url: "http://192.168.1.100:81"
    username: "[email protected]"
    password: "your-password"

  pihole:
    enabled: true
    url: "http://192.168.1.53"
    api_key: "your-api-key"

  # ... more services

MCP client configuration enables you to connect from client applications. A typical client JSON includes the MCP server URL and the transport method. For example, you can configure a client to connect to a remote MCP endpoint.

Available tools

homelab_health_check

Check health of all enabled services to verify they are functioning and reachable.

homelab_list_services

List configured services and their current status in the MCP configuration.

npm_list_proxy_hosts

List all proxy hosts configured in Nginx Proxy Manager through MCP.

npm_list_ssl_certificates

List SSL certificates managed by Nginx Proxy Manager.

npm_get_proxy_host

Get details for a specific proxy host managed by Nginx Proxy Manager.

npm_enable_proxy_host

Enable a proxy host previously disabled in Nginx Proxy Manager.

npm_disable_proxy_host

Disable a proxy host in Nginx Proxy Manager.

npm_check_expiring_certificates

Find SSL certificates that are nearing expiration.

pihole_get_summary

Retrieve DNS query statistics from Pi-hole.

pihole_get_top_queries

Show the top domain queries processed by Pi-hole.

pihole_get_top_blocked

Show the top blocked domains on Pi-hole.

pihole_enable

Enable ad blocking by Pi-hole.

pihole_disable

Disable ad blocking in Pi-hole.

pihole_get_query_types

Provide a breakdown of DNS query types seen by Pi-hole.

uptime_get_status_page

Get the status page information for Uptime Kuma monitors.

uptime_get_heartbeats

Retrieve heartbeat data from uptime monitors.

uptime_get_monitor_summary

Summarize the status of all uptime Kuma monitors.

portainer_list_endpoints

List Docker environments configured in Portainer.

portainer_list_containers

List containers on a Portainer endpoint.

portainer_get_endpoint_stats

Get stats for containers, images, and volumes in Portainer.

portainer_container_action

Start, stop, or restart containers via Portainer.

portainer_list_stacks

List Docker Compose stacks managed by Portainer.

ups_get_status

Get current UPS status such as battery level and runtime.

ups_get_all_variables

Retrieve all UPS variables exposed by the device.

ups_list_devices

List UPS devices available to MCP.

ups_check_power_status

Quick check of the power status from UPS devices.

orbi_get_info

Fetch router model, serial, and firmware information for Netgear Orbi.

orbi_get_attached_devices

List connected devices with IP, MAC, and signal strength.

orbi_get_traffic_meter

View bandwidth usage statistics today and month.

orbi_block_device

Block a device by MAC address on the Orbi network.

orbi_allow_device

Unblock a previously blocked device on the Orbi network.

orbi_check_firmware

Check for available firmware updates on Orbi.

orbi_get_guest_wifi_status

Get the status of guest WiFi networks.

orbi_set_guest_wifi

Enable or disable guest WiFi networks on Orbi.

orbi_reboot

Reboot the Orbi router (causes temporary network outage).