# 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.

```json
{
  "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.

## 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

```sh
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.