# Claude Homelab

> Comprehensive Agents, Commands, Hooks, and Skills for homelab service management - media automation, infrastructure monitoring, document management, and more

- **Type:** MCP server
- **Install:** `agentstack add mcp-jmagar-claude-homelab`
- **Verified:** Pending review
- **Seller:** [jmagar](https://agentstack.voostack.com/s/jmagar)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jmagar](https://github.com/jmagar)
- **Source:** https://github.com/jmagar/claude-homelab

## Install

```sh
agentstack add mcp-jmagar-claude-homelab
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Claude Homelab

Current release: 1.4.0.

Homelab plugin hub for Claude Code, Codex, and Gemini. This repository is the source of truth for the `homelab-core` plugin, bundled skill-only integrations, agents, commands, and shared credential bootstrapping.

## Overview

`claude-homelab` serves three roles at once:

- The `homelab-core` plugin published through the Claude marketplace
- The canonical mono-repo for 16 bundled skill-only service integrations
- The source for Codex and Gemini extension manifests that mirror the same workflow surface

The repo root is the plugin root. Do not edit generated copies in `~/.claude/` or `~/.claude/plugins/cache/` directly.

## Installation

### Claude marketplace

```bash
/plugin marketplace add jmagar/claude-homelab
/plugin install homelab-core @jmagar-claude-homelab
```

After install, Claude Code downloads the plugin into `~/.claude/plugins/cache/`. No symlinks are created on this path.

### Bash / symlink install

```bash
curl -sSL https://raw.githubusercontent.com/jmagar/claude-homelab/main/scripts/install.sh | bash
```

Or, if you already have the repo cloned:

```bash
./scripts/install.sh
```

The installer:

1. Checks prerequisites (`git`, `jq`, `curl`)
2. Clones the repo to `~/claude-homelab` (or pulls if it exists)
3. Runs `setup-creds.sh` — creates `~/.claude-homelab/.env` from `.env.example` with `chmod 600`
4. Runs `setup-symlinks.sh` — symlinks skills, agents, and commands into `~/.claude/`
5. Runs `verify.sh` — confirms every symlink and required file is in place
6. Prints next steps

## Credential Model

All credentials for every service live in a single file:

```
~/.claude-homelab/.env
```

This file is created from `.env.example` at install time and is never committed. Set it up interactively after install:

```bash
# Interactive wizard (preferred)
# Open Claude Code and run:
/homelab-core:setup

# Or configure manually
$EDITOR ~/.claude-homelab/.env
```

Security requirements:

- `~/.claude-homelab/.env` must have `chmod 600` (owner read/write only)
- Never commit `.env` — it is gitignored
- Never log credentials, even in debug mode
- Use `.env.example` as the template (tracked in git, placeholder values only)

All service scripts load credentials via `scripts/load-env.sh`:

```bash
source "${CLAUDE_PLUGIN_ROOT:-$HOME/claude-homelab}/scripts/load-env.sh"
load_env_file || exit 1
validate_env_vars "SERVICE_URL" "SERVICE_API_KEY"
```

### Environment Variable Reference

Variables are grouped by service. Copy `.env.example` to `~/.claude-homelab/.env` and replace placeholder values.

#### Media

| Variable | Required | Description |
|---|---|---|
| `PLEX_URL` | yes | Plex server base URL |
| `PLEX_TOKEN` | yes | Plex authentication token |
| `OVERSEERR_URL` | yes | Overseerr base URL (skill) |
| `OVERSEERR_API_KEY` | yes | Overseerr API key (skill) |
| `RADARR_URL` | yes | Radarr base URL |
| `RADARR_API_KEY` | yes | Radarr API key |
| `RADARR_DEFAULT_QUALITY_PROFILE` | no | Default quality profile ID (default: `1`) |
| `SONARR_URL` | yes | Sonarr base URL |
| `SONARR_API_KEY` | yes | Sonarr API key |
| `SONARR_DEFAULT_QUALITY_PROFILE` | no | Default quality profile ID (default: `1`) |
| `PROWLARR_URL` | yes | Prowlarr base URL |
| `PROWLARR_API_KEY` | yes | Prowlarr API key |
| `TAUTULLI_URL` | yes | Tautulli base URL |
| `TAUTULLI_API_KEY` | yes | Tautulli API key |

#### Downloads

| Variable | Required | Description |
|---|---|---|
| `SABNZBD_URL` | yes | SABnzbd base URL |
| `SABNZBD_API_KEY` | yes | SABnzbd API key |
| `QBITTORRENT_URL` | yes | qBittorrent WebUI URL |
| `QBITTORRENT_USERNAME` | yes | qBittorrent username |
| `QBITTORRENT_PASSWORD` | yes | qBittorrent password |

#### Infrastructure

| Variable | Required | Description |
|---|---|---|
| `UNRAID_SERVER1_NAME` | yes | Display name for first Unraid server |
| `UNRAID_SERVER1_URL` | yes | Unraid GraphQL endpoint (skill) |
| `UNRAID_SERVER1_API_KEY` | yes | Unraid API key (skill) |
| `UNRAID_SERVER2_NAME` | no | Display name for second Unraid server |
| `UNRAID_SERVER2_URL` | no | Second Unraid GraphQL endpoint |
| `UNRAID_SERVER2_API_KEY` | no | Second Unraid API key |
| `UNIFI_URL` | yes | UniFi controller URL (skill) |
| `UNIFI_USERNAME` | yes | UniFi username |
| `UNIFI_PASSWORD` | yes | UniFi password |
| `UNIFI_SITE` | no | UniFi site name (default: `default`) |
| `TAILSCALE_API_KEY` | yes | Tailscale API key |
| `TAILSCALE_TAILNET` | yes | Tailscale tailnet name or `-` |
| `ZFS_HOST` | yes | Host where ZFS commands run |
| `SWAG_HOST` | yes | SWAG reverse proxy host |
| `SWAG_CONTAINER_NAME` | no | SWAG container name (default: `swag`) |
| `SWAG_APPDATA_PATH` | no | SWAG appdata path |
| `SWAG_COMPOSE_PATH` | no | SWAG compose file path |

#### Utilities and Document Management

| Variable | Required | Description |
|---|---|---|
| `LINKDING_URL` | yes | Linkding bookmark manager URL |
| `LINKDING_API_KEY` | yes | Linkding API token |
| `MEMOS_URL` | yes | Memos server URL |
| `MEMOS_API_TOKEN` | yes | Memos API token |
| `BYTESTASH_URL` | yes | ByteStash snippet manager URL |
| `BYTESTASH_API_KEY` | yes | ByteStash API key |
| `PAPERLESS_URL` | yes | Paperless-ngx base URL |
| `PAPERLESS_API_TOKEN` | yes | Paperless-ngx API token |
| `RADICALE_URL` | yes | Radicale CalDAV/CardDAV URL |
| `RADICALE_USERNAME` | yes | Radicale username |
| `RADICALE_PASSWORD` | yes | Radicale password |
| `GOTIFY_URL` | yes | Gotify push notification URL (skill) |
| `GOTIFY_TOKEN` | yes | Gotify app token (skill) |

#### Research and Dev Tools

| Variable | Required | Description |
|---|---|---|
| `NOTEBOOKLM_COOKIE` | yes | NotebookLM session cookie |
| `NOTEBOOKLM_AUTH_JSON` | no | Full auth JSON blob (alternative to cookie) |
| `NOTEBOOKLM_LOG_LEVEL` | no | Log verbosity (default: `INFO`) |
| `GITHUB_TOKEN` | yes | GitHub personal access token (gh-address-comments) |
| `GLANCES_URL` | no | Glances web interface URL |
| `GLANCES_USERNAME` | no | Glances username (if auth enabled) |
| `GLANCES_PASSWORD` | no | Glances password (if auth enabled) |

#### MCP Server Variables

Each external MCP plugin has its own block of server-config vars. See `.env.example` for the full list. Key patterns:

| Pattern | Description |
|---|---|
| `*_MCP_TOKEN` | Bearer token for MCP server auth |
| `*_MCP_HOST` | Bind host (default: `0.0.0.0`) |
| `*_MCP_PORT` | Listen port |
| `*_MCP_TRANSPORT` | Transport protocol (`streamable-http` or `http`) |
| `*_MCP_NO_AUTH` | Disable auth (set `true` for local-only installs) |
| `*_MCP_ALLOW_DESTRUCTIVE` | Allow destructive operations (default: `false`) |
| `ALLOW_DESTRUCTIVE` | Shared fallback for MCP repos that read this directly |
| `ALLOW_YOLO` | Shared fallback — skip confirmation prompts |
| `DOCKER_NETWORK` | Shared Docker network name |
| `LOG_LEVEL` | Shared log verbosity |

## Commands

### Root Commands

| Command | Argument | Description |
|---|---|---|
| `/check` | `[instructions]` | Read the latest screenshot from `~/Pictures/Screenshots` and describe it. Pass optional instructions (e.g., "extract the text", "what error is shown"). |
| `/deploy` | `[plugin-name]` | Build and start MCP plugin containers via `docker compose up --build -d`. Deploys all external plugins by default. Pass a plugin name to deploy only that one. Reads compose files from `~/.claude/plugins/cache/claude-homelab///`. Skips `tests/` subdirs. Reports a status table with notes on failures. |
| `/quick-push` | — | Standardized commit-and-push workflow. Checks branch (creates feature branch if on main), bumps version in all manifests, updates `CHANGELOG.md`, stages all changes, commits with co-authorship signature, pushes, then invokes `save-to-md` and writes Neo4j commit graph entries. |
| `/save-to-md` | `[output-path]` | Document the full session as a Markdown file. Defaults to `docs/sessions/YYYY-MM-DD-description.md`. Creates Neo4j entities and relations for files, services, features, and bugs touched in the session. |
| `/validate-plan` | `` | Audit a technical implementation plan against homelab standards. Checks for exposed secrets, correct credential loading pattern (`scripts/load-env.sh`), required docs (`README.md`, `SKILL.md`, references), `confirm=True` gate on destructive actions, and standard directory structure. Outputs a compliance table and required changes list. |

### `/homelab:*` Commands

| Command | Description |
|---|---|
| `/homelab:system-resources` | Snapshot CPU, RAM, temperatures, and load average. Identifies high-CPU processes, memory pressure, temperature anomalies, and provides optimization recommendations. Uses `uptime`, `free`, `top`, and `sensors`. |
| `/homelab:docker-health` | Audit all Docker containers. Flags unexpected exits, restart loops, unhealthy containers, and resource over-use (CPU > 80%, memory > 90%). Provides per-container recommendations. |
| `/homelab:disk-space` | Analyze disk usage across all mount points. Identifies filesystems above 80% or 95% usage, space hogs, log rotation issues, Docker volume orphans, and suggests cleanup targets. |
| `/homelab:zfs-health` | Full ZFS health check. Reports pool state (ONLINE/DEGRADED/FAULTED), device errors, checksum errors, resilvering, scrub status, ARC hit ratio, snapshot accumulation, and per-dataset usage. Outputs a health score and prioritized action list. |

### `/notebooklm:*` Commands

| Command | Argument | Description |
|---|---|---|
| `/notebooklm:create` | `"Title" [url1] [url2] ...` | Create a new NotebookLM notebook. Optionally add URLs, PDFs, Google Docs, YouTube links, audio, video, or image files as sources. Reports the new notebook ID. |
| `/notebooklm:ask` | `"question"` | Chat with NotebookLM about the current notebook. Options: `--json` for source citations, `-n ` to target a specific notebook. |
| `/notebooklm:source` | `add  \| list \| wait  \| fulltext  \| add-research "query"` | Manage notebook sources. Add a URL or file, list current sources, wait for a source to finish processing, retrieve full text, or trigger web research. Supports `-n ` for targeting. |
| `/notebooklm:generate` | ` ["instructions"]` | Generate an artifact. Types: `audio`, `video`, `quiz`, `report`, `mind-map`, `flashcards`, `slide-deck`, `infographic`, `data-table`. Each type has format, length, style, and difficulty options. |
| `/notebooklm:download` | ` [output-path]` | Download a generated artifact to a local file. Supports `--all` and `--format json\|md\|html`. Artifact must be fully generated first. |
| `/notebooklm:list` | `[notebooks\|sources\|artifacts]` | List notebooks (default), sources in the current notebook, or generated artifacts. Presents results in a table with IDs, names, and status. |
| `/notebooklm:research` | `"query" [--mode fast\|deep]` | Run web research and import results as notebook sources. Fast mode: 30 seconds to 2 minutes. Deep mode: 15 to 30+ minutes, use `--no-wait` and follow up with `notebooklm research wait --import-all`. |

#### `/notebooklm:generate` Type Reference

| Type | Key Options | Approximate Time |
|---|---|---|
| `audio` (podcast) | `--format deep-dive\|brief\|critique\|debate`, `--length short\|default\|long` | 10–20 min |
| `video` | `--format explainer\|brief`, `--style auto\|classic\|whiteboard\|kawaii\|...` | 15–45 min |
| `slide-deck` | `--format detailed\|presenter`, `--length default\|short` | 5–15 min |
| `infographic` | `--orientation landscape\|portrait\|square`, `--detail concise\|standard\|detailed` | 5–15 min |
| `report` | `--format briefing-doc\|study-guide\|blog-post\|custom` | 5–15 min |
| `mind-map` | — | Instant |
| `data-table` | description required | 5–15 min |
| `quiz` | `--difficulty easy\|medium\|hard`, `--quantity fewer\|standard\|more` | 5–15 min |
| `flashcards` | `--difficulty easy\|medium\|hard`, `--quantity fewer\|standard\|more` | 5–15 min |

All types support `-s/--source`, `--language`, `--json`, and `--retry N`.

## Skills

18 skill directories live under `skills/`. Each is an independent unit with a `SKILL.md` (Claude-facing) and typically a `README.md`, `scripts/`, and `references/` directory.

### Core Skills (2)

| Skill | Invocation | Purpose |
|---|---|---|
| `homelab-setup` | `/homelab-core:setup` | Interactive credential setup wizard. Guides through configuring `~/.claude-homelab/.env` for each service the user runs. Creates the file from `.env.example` if missing. |
| `homelab-health` | `/homelab-core:health` | Unified service health dashboard. Runs `scripts/check-health.sh` to curl-check every configured service and outputs a JSON health summary. |

### Service Skills (16)

| Skill | Category | Purpose |
|---|---|---|
| `plex` | media | Browse Plex libraries, search media, check active sessions and streams, view recently added content |
| `radarr` | media | Manage Radarr movie library — search, add, monitor, and track download status |
| `sonarr` | media | Manage Sonarr TV library — search, add series, monitor seasons and episodes |
| `prowlarr` | media | Manage Prowlarr indexers — search across all indexers, test connectivity, view stats |
| `tautulli` | media | Query Tautulli play history, user activity, library stats, and notification logs |
| `sabnzbd` | downloads | Monitor SABnzbd queue, speed, and history; manage download jobs |
| `qbittorrent` | downloads | Manage qBittorrent torrents — list, add, pause, resume, and remove downloads |
| `tailscale` | infrastructure | Query Tailscale network status, list devices, check connectivity, and manage ACLs |
| `zfs` | infrastructure | ZFS pool and dataset management — status, snapshots, scrubs, and space reporting |
| `linkding` | utilities | Manage Linkding bookmarks — search, add, tag, and organize saved links |
| `memos` | utilities | Create and query Memos notes — add quick notes, search by tag or content |
| `bytestash` | utilities | Manage ByteStash code snippets — save, search, and retrieve frequently-used code |
| `paperless-ngx` | utilities | Search and manage Paperless-ngx document archive — query by content, tag, or correspondent |
| `radicale` | utilities | Interact with Radicale CalDAV/CardDAV — list calendars and contacts, query events |
| `notebooklm` | research | NotebookLM CLI wrapper for deep AI research, source management, Q&A, and artifact generation |
| `gh-address-comments` | dev-tools | Address GitHub PR review comments — fetch, triage, and resolve review feedback |

## Agents

### `notebooklm-specialist`

**File:** `agents/notebooklm-specialist.md`

**Color:** magenta

**Tools:** `Bash`, `Read`, `Write`, `SendMessage`

**Memory:** user (persistent across sessions)

The `notebooklm-specialist` is a research analyst agent for deep AI-powered research workflows. It is spawned by an orchestrator with a pre-created notebook ID, output directory, and research brief. The agent:

1. Starts deep web research immediately (`notebooklm source add-research --mode deep --no-wait`) — this is always the first action since it takes 15–30+ minutes
2. Adds source URLs relayed from the orchestrator as they arrive (max 50 per notebook)
3. Waits for deep research to complete and auto-imports discovered sources
4. Conducts an extensive Q&A session (10–20 questions across overview, comparison, technical, critical, practical, and future-directions categories)
5. Uses `--json` flag to capture citation data with every answer
6. Writes findings to `{output_dir}/findings/notebooklm-findings.md`
7. Signals completion to the orchestrator via `SendMessage`

**Critical constraint:** Always use `-n ` or `--notebook `. Never use `notebooklm use ` — that command modifies shared state and is unsafe in parallel workflows.

The agent maintains persistent memory of effective research query patterns, timing benchmarks, and NotebookLM-specific quirks across sessions.

## Marketplace Scope

The `.claude-plugin/marketplace.json` catalog covers 27 plugins total.

### 1 core plugin

| Plugin | Source | Description |
|---|---|---|
| `homelab-core` | this repo | Agents, co

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jmagar](https://github.com/jmagar)
- **Source:** [jmagar/claude-homelab](https://github.com/jmagar/claude-homelab)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-jmagar-claude-homelab
- Seller: https://agentstack.voostack.com/s/jmagar
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.