Homelab MCP Server

A constrained Model Context Protocol adapter for Homelab Core. It lets an AI assistant inspect health, service verification, redacted logs, nodes, jobs, and correlated job events without editing the deployment repository or opening SSH sessions.

Read tools are the default. Set HOMELAB_MCP_ALLOW_CHANGES=1 only when you want the two job-queuing tools to appear. Those tools still use Core's typed operations, audit trail, queue limits, and idempotency contracts; this server never exposes arbitrary shell, file access, secrets, or raw node tasks.

Local configuration

Run the server where it can see Core's Unix socket and UI transport token. The UI token is the correct least-privilege local credential for diagnostics; do not copy the controller's root-only local token out of its data volume.

{
  "mcpServers": {
    "homelab": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--network", "none",
        "--read-only",
        "--cap-drop", "ALL",
        "--security-opt", "no-new-privileges:true",
        "--volume", "homelab_controller-socket:/run/homelab-controller:ro",
        "--env", "HOMELAB_CONTROLLER_SOCKET=/run/homelab-controller/controller.sock",
        "--env", "HOMELAB_CONTROLLER_TOKEN_FILE=/run/homelab-controller/ui.token",
        "--env", "HOMELAB_CONTROLLER_ROLE=ui",
        "ghcr.io/breixopd/homelab-mcp:1.0.0"
      ]
    }
  }
}

The example volume name is the default managed deployment name. If a Compose project prefix was customized, replace it with the actual controller-socket volume. The MCP process needs no network access: all traffic stays on the local Unix socket. Token files are read in place, never copied into command arguments or MCP responses.

Related MCP server: homelab-ai

Tools

• homelab_get_overview

• homelab_list_services

• homelab_get_service_diagnostics

• homelab_get_service_verification

• homelab_list_nodes

• homelab_list_jobs

• homelab_get_job

• homelab_get_job_events

• homelab_run_service_verification (changes enabled only)

• homelab_run_maintenance (changes enabled only)

Build and test

npm ci
npm run check
docker build --pull -t homelab-mcp:test .

The initial transport is stdio. A remote HTTP listener is intentionally absent until Core provides a dedicated scoped observer credential; exposing the full local/UI controller token over a network would be the wrong security boundary.