# Homelab MCP Server

**Last updated:** 2026-03-21

The homelab MCP (Model Context Protocol) server exposes tools that allow AI assistants (OpenCode/Claude) to interact directly with homelab infrastructure. It runs as a stdio subprocess started by OpenCode on session init.

---

## Location & Config

| Item | Path |
|------|------|
| Server source | `scripts/homelab-mcp/server.py` |
| OpenCode config | `~/.config/opencode/opencode.json` |
| Runtime | Python 3, `fastmcp` library |
| Transport | stdio (started per-session by OpenCode) |

Changes to `server.py` take effect on the **next OpenCode session** (the server is restarted each session).

---

## Tool Categories

### 1. Portainer — Docker orchestration

Manages containers and stacks across all 5 Portainer endpoints.

| Tool | What it does |
|------|-------------|
| `check_portainer` | Health check — version and stack count |
| `list_endpoints` | List all endpoints (Atlantis, Calypso, NUC, Homelab VM, RPi5) |
| `list_stacks` | List all stacks, optionally filtered by endpoint |
| `get_stack` | Get details of a specific stack by name or ID |
| `redeploy_stack` | Trigger GitOps redeploy (pull from Git + redeploy) |
| `list_containers` | List running containers on an endpoint |
| `get_container_logs` | Fetch recent logs from a container |
| `restart_container` | Restart a container |
| `start_container` | Start a stopped container |
| `stop_container` | Stop a running container |
| `list_stack_containers` | List all containers belonging to a stack |

**Endpoints:** `atlantis` (id=2), `calypso` (id=443397), `nuc` (id=443398), `homelab` (id=443399), `rpi5` (id=443395)

---

### 2. Gitea — Source control

Interacts with the self-hosted Gitea instance at `git.vish.gg`.

| Tool | What it does |
|------|-------------|
| `gitea_list_repos` | List all repos in the org |
| `gitea_list_issues` | List open/closed issues for a repo |
| `gitea_create_issue` | Create a new issue |
| `gitea_list_branches` | List branches for a repo |

**Default org:** `vish` — repo names can be `homelab` or `vish/homelab`

---

### 3. AdGuard — Split-horizon DNS

Manages DNS rewrite rules on the Calypso AdGuard instance (`192.168.0.250:9080`).

Critical context: the wildcard `*.vish.gg → 100.85.21.51` (matrix-ubuntu Tailscale IP) requires specific overrides for services that internal hosts need to reach directly (e.g. `pt.vish.gg`, `sso.vish.gg`, `git.vish.gg` all need `→ 192.168.0.154`).

| Tool | What it does |
|------|-------------|
| `adguard_list_rewrites` | List all DNS overrides |
| `adguard_add_rewrite` | Add a new domain → IP override |
| `adguard_delete_rewrite` | Remove a DNS override |

---

### 4. NPM — Nginx Proxy Manager

Manages reverse proxy hosts and SSL certs on matrix-ubuntu (`192.168.0.154:81`).

**Critical cert rule:** Never reuse an existing `npm-N` ID. Always use the next available number when adding new certs.

| Tool | What it does |
|------|-------------|
| `npm_list_proxy_hosts` | List all proxy hosts with domain, forward target, cert ID |
| `npm_list_certs` | List all SSL certs with type and expiry |
| `npm_get_proxy_host` | Get full details of a proxy host including advanced nginx config |
| `npm_update_cert` | Swap the SSL cert on a proxy host |

**Cert reference:**
| ID | Domain | Type |
|----|--------|------|
| npm-1 | `*.vish.gg` + `vish.gg` | Cloudflare Origin (proxied only) |
| npm-6 | `mx.vish.gg` | Let's Encrypt |
| npm-7 | `livekit.mx.vish.gg` | Let's Encrypt |
| npm-8 | `*.vish.gg` CF Origin | Cloudflare Origin (all proxied `*.vish.gg`) |
| npm-9 | `*.thevish.io` | Let's Encrypt |
| npm-10 | `*.crista.love` | Let's Encrypt |
| npm-11 | `pt.vish.gg` | Let's Encrypt |
| npm-12 | `sso.vish.gg` | Let's Encrypt |

---

### 5. Headscale — Tailnet management

Manages nodes and pre-auth keys via SSH to Calypso → `docker exec headscale`.

| Tool | What it does |
|------|-------------|
| `headscale_list_nodes` | List all tailnet nodes with IPs and online status |
| `headscale_create_preauth_key` | Generate a new node auth key (with expiry/reusable/ephemeral options) |
| `headscale_delete_node` | Remove a node from the tailnet |
| `headscale_rename_node` | Rename a node's given name |

**Login server:** `https://headscale.vish.gg:8443`
**New node command:** `tailscale up --login-server=https://headscale.vish.gg:8443 --authkey=<key> --accept-routes=false`

---

### 6. Authentik — SSO identity provider

Manages OAuth2/OIDC apps, providers, and users at `sso.vish.gg`.

| Tool | What it does |
|------|-------------|
| `authentik_list_applications` | List all SSO apps with slug, provider, launch URL |
| `authentik_list_providers` | List all OAuth2/proxy providers with PK and type |
| `authentik_list_users` | List all users with email and active status |
| `authentik_update_app_launch_url` | Update the dashboard tile URL for an app |
| `authentik_set_provider_cookie_domain` | Set cookie domain on a proxy provider (must be `vish.gg` to avoid redirect loops) |

**Critical:** All Forward Auth proxy providers must have `cookie_domain: vish.gg` or they cause `ERR_TOO_MANY_REDIRECTS`.

---

### 7. Cloudflare — DNS management

Manages DNS records for the `vish.gg` zone.

| Tool | What it does |
|------|-------------|
| `cloudflare_list_dns_records` | List all DNS records, optionally filtered by name |
| `cloudflare_create_dns_record` | Create a new A/CNAME/TXT record |
| `cloudflare_delete_dns_record` | Delete a DNS record by ID |
| `cloudflare_update_dns_record` | Update an existing record's content or proxied status |

**Proxied (orange cloud):** Most `*.vish.gg` services
**Unproxied (DNS-only):** `mx.vish.gg`, `headscale.vish.gg`, `livekit.mx.vish.gg`, `pt.vish.gg`, `sso.vish.gg`, `derp*.vish.gg`

---

### 8. Uptime Kuma — Monitoring

Manages monitors and groups via SSH to Pi-5 → SQLite DB manipulation.

**Always call `kuma_restart` after adding or modifying monitors** — Kuma caches config in memory.

| Tool | What it does |
|------|-------------|
| `kuma_list_monitors` | List all monitors with type, status, URL/hostname, group |
| `kuma_list_groups` | List all group monitors with IDs (for use as `parent_id`) |
| `kuma_add_monitor` | Add a new http/port/ping/group monitor |
| `kuma_set_parent` | Assign a monitor to a group |
| `kuma_restart` | Restart Kuma container to apply DB changes |

**Monitor group hierarchy:**
```
Homelab (3) → Atlantis (4), Calypso (49), Concord_NUC (44),
              Raspberry Pi 5 (91), Guava (73), Setillo (58),
              Proxmox_NUC (71), Seattle (111),
              Matrix-Ubuntu (115), Moon (114)
```

---

### 9. Prometheus — Metrics queries

Queries the Prometheus instance at `192.168.0.210:9090`.

| Tool | What it does |
|------|-------------|
| `prometheus_query` | Run a PromQL instant query |
| `prometheus_targets` | List all scrape targets and their health |

---

### 10. Grafana — Dashboards & alerts

Inspects dashboards and alert rules at `192.168.0.210:3300`.

| Tool | What it does |
|------|-------------|
| `grafana_list_dashboards` | List all dashboards with folder |
| `grafana_list_alerts` | List all alert rules and current state |

---

### 11. Media — Sonarr / Radarr / SABnzbd

Manages the media download stack on Atlantis.

| Tool | What it does |
|------|-------------|
| `sonarr_list_series` | List TV series, optionally filtered by title |
| `sonarr_queue` | Show current Sonarr download queue |
| `radarr_list_movies` | List movies, optionally filtered by title |
| `radarr_queue` | Show current Radarr download queue |
| `sabnzbd_queue` | Show SABnzbd download queue with progress |
| `sabnzbd_pause` | Pause the SABnzbd queue |
| `sabnzbd_resume` | Resume the SABnzbd queue |

---

### 12. SSH — Remote command execution

Runs shell commands on homelab hosts via SSH.

| Tool | What it does |
|------|-------------|
| `ssh_exec` | Run a command on a named host |

**Known hosts:** `atlantis`, `calypso`, `setillo`, `setillo-root`, `nuc`, `homelab-vm`, `rpi5`, `pi-5`, `matrix-ubuntu`, `moon`, `olares`, `guava`, `pve`, `seattle-tailscale`, `gl-mt3000`

---

### 13. Filesystem — Local file access

Read/write files on the homelab-vm filesystem.

| Tool | What it does |
|------|-------------|
| `fs_read` | Read a file (allowed: `/home/homelab`, `/tmp`) |
| `fs_write` | Write a file (allowed: `/home/homelab`, `/tmp`) |
| `fs_list` | List directory contents |

---

### 14. Repo — Homelab repository inspection

Inspects the homelab Git repository at `/home/homelab/organized/repos/homelab`.

| Tool | What it does |
|------|-------------|
| `list_homelab_services` | List all compose files, optionally filtered by host |
| `get_compose_file` | Read a compose file by partial path or name (searches `docker-compose.yml/yaml` and standalone `*.yaml/*.yml` stacks) |

---

### 15. Notifications — ntfy push

Sends push notifications via the self-hosted ntfy instance.

| Tool | What it does |
|------|-------------|
| `send_notification` | Send a push notification to ntfy topic |

**Default topic:** `homelab-alerts`  
**Priorities:** `urgent`, `high`, `default`, `low`, `min`

---

### 16. Health checks

| Tool | What it does |
|------|-------------|
| `check_url` | HTTP health check against a URL with expected status code |

---

## Bug Fixes Applied (2026-03-21)

| Bug | Symptom | Fix |
|-----|---------|-----|
| `list_homelab_services` | `AttributeError: 'str' object has no attribute 'parts'` — crashed every call | Changed `str(f).parts` → `f.parts` |
| `get_compose_file` | Couldn't find standalone stack files like `homarr.yaml`, `whisparr.yaml` | Extended search to all `*.yaml/*.yml`, prefers `docker-compose.*` when both match |
| `check_portainer` | Type error on `stacks.get()` — stacks is a list not a dict | Added `isinstance` guards |
| `gitea_create_issue` | Type error on `data['number']` — subscript on `dict \| list` union | Added `isinstance(data, dict)` guard |

---

## Adding New Tools

1. Add helper function (e.g. `_myservice(...)`) to the helpers section
2. Add `@mcp.tool()` decorated function with a clear docstring
3. Update the `instructions=` string in `mcp = FastMCP(...)` with the new category
4. Add `pragma: allowlist secret` to any token/key constants
5. Commit and push — changes take effect next OpenCode session

---

## Related docs

- `docs/admin/ai-integrations.md` — AI/LLM integrations overview
- `docs/troubleshooting/matrix-ssl-authentik-incident-2026-03-19.md` — NPM cert reference
- `docs/services/individual/uptime-kuma.md` — Kuma monitor group reference