# Homelab MCP Server

MCP (Model Context Protocol) server that exposes homelab infrastructure management as tool calls for Claude Code. Provides 64 tools across 14 service integrations.

## Setup

```bash
pip install -r requirements.txt
```

The server runs as a stdio MCP server, configured in Claude Code's project settings:

```json
{
  "mcpServers": {
    "homelab": {
      "type": "stdio",
      "command": "python3",
      "args": ["/home/homelab/organized/repos/homelab/scripts/homelab-mcp/server.py"]
    }
  }
}
```

## Architecture

- **server.py** -- single-file FastMCP server, all tools and configuration
- **`@_safe` decorator** -- wraps every tool function so unhandled exceptions (HTTP timeouts, network errors, API failures) return error strings instead of crashing the server process. Added after repeated MCP disconnects during long sessions.
- **Credentials** -- hardcoded in config block at top of server.py (private repo only; public mirror uses `REDACTED_*` placeholders)

## Tools (64 total)

### Portainer -- Docker Orchestration (11 tools)

Manages containers and stacks across 5 endpoints: atlantis, calypso, nuc, homelab, rpi5.

| Tool | Description |
|------|-------------|
| `list_endpoints` | List all Portainer environments with connection status |
| `list_stacks` | List all stacks, optionally filtered by endpoint |
| `get_stack` | Get detailed stack info (git config, env vars, dates) |
| `redeploy_stack` | GitOps redeploy -- pull latest from Git and redeploy |
| `list_containers` | List containers on an endpoint, with optional name filter |
| `get_container_logs` | Fetch recent log lines from a container |
| `restart_container` | Restart a container by name or ID |
| `stop_container` | Stop a running container |
| `start_container` | Start a stopped container |
| `list_stack_containers` | List all containers in a specific stack |
| `check_portainer` | Health check -- version, stack count |

### Gitea -- Git Repository Management (4 tools)

Self-hosted git at git.vish.gg, org=vish.

| Tool | Description |
|------|-------------|
| `gitea_list_repos` | List repositories, optionally filtered by owner |
| `gitea_list_issues` | List issues for a repo (open/closed/all) |
| `gitea_create_issue` | Create a new issue |
| `gitea_list_branches` | List branches for a repo |

### AdGuard -- DNS Rewrites (3 tools)

Split-horizon DNS management on Calypso (192.168.0.250:9080).

| Tool | Description |
|------|-------------|
| `adguard_list_rewrites` | List all DNS rewrite rules |
| `adguard_add_rewrite` | Add a DNS rewrite (domain -> IP) |
| `adguard_delete_rewrite` | Delete a DNS rewrite rule |

### NPM -- Nginx Proxy Manager (4 tools)

Reverse proxy on matrix-ubuntu (192.168.0.154:81).

| Tool | Description |
|------|-------------|
| `npm_list_proxy_hosts` | List proxy hosts, optionally filtered by domain |
| `npm_list_certs` | List SSL certificates with expiry dates |
| `npm_get_proxy_host` | Get full config for a specific proxy host |
| `npm_update_cert` | Update the SSL certificate on a proxy host |

### Headscale -- Tailscale Coordination (4 tools)

Self-hosted Tailscale control server on Calypso. Executes via SSH + `docker exec`.

| Tool | Description |
|------|-------------|
| `headscale_list_nodes` | List all tailnet nodes with online status and IPs |
| `headscale_create_preauth_key` | Create a pre-auth key for node registration |
| `headscale_delete_node` | Remove a node from the tailnet |
| `headscale_rename_node` | Rename a node |

### Authentik -- SSO Identity Provider (9 tools)

SSO at sso.vish.gg on Calypso. All proxy providers need `cookie_domain=vish.gg`.

| Tool | Description |
|------|-------------|
| `authentik_list_applications` | List all SSO applications |
| `authentik_list_providers` | List OAuth2/OIDC/proxy providers |
| `authentik_list_users` | List all users |
| `authentik_update_app_launch_url` | Update an application's dashboard URL |
| `authentik_set_provider_cookie_domain` | Set cookie domain on a proxy provider |
| `authentik_create_proxy_provider` | Create a new proxy provider (auto-binds to outpost) |
| `authentik_create_application` | Create an application linked to a provider |
| `authentik_list_sessions` | List active authenticated sessions |
| `authentik_delete_session` | Invalidate a session |
| `authentik_get_events` | Get audit log events (logins, failures, policy denials) |

### Cloudflare -- DNS Management (4 tools)

DNS for vish.gg zone.

| Tool | Description |
|------|-------------|
| `cloudflare_list_dns_records` | List DNS records, optionally filtered by name |
| `cloudflare_create_dns_record` | Create A/CNAME/TXT record (proxied by default) |
| `cloudflare_delete_dns_record` | Delete a DNS record by ID |
| `cloudflare_update_dns_record` | Update record content or proxied status |

### Uptime Kuma -- Monitoring (5 tools)

Monitoring on Pi-5 via SSH + SQLite. **Must call `kuma_restart` after add/modify.**

| Tool | Description |
|------|-------------|
| `kuma_list_monitors` | List all monitors with status and type |
| `kuma_list_groups` | List monitor groups (for parent IDs) |
| `kuma_add_monitor` | Add http/port/ping/group monitor |
| `kuma_set_parent` | Set or clear a monitor's parent group |
| `kuma_restart` | Restart Kuma container to apply DB changes |

### Prometheus -- Metrics (2 tools)

PromQL queries against homelab-vm (192.168.0.210:9090).

| Tool | Description |
|------|-------------|
| `prometheus_query` | Run an instant PromQL query |
| `prometheus_targets` | List scrape targets with health status |

### Grafana -- Dashboards (2 tools)

Dashboard inspection on homelab-vm (192.168.0.210:3300).

| Tool | Description |
|------|-------------|
| `grafana_list_dashboards` | List all dashboards |
| `grafana_list_alerts` | List alert rules and state |

### Sonarr / Radarr -- Media Libraries (4 tools)

TV and movie management on Atlantis.

| Tool | Description |
|------|-------------|
| `sonarr_list_series` | List TV series, optionally filtered by name |
| `sonarr_queue` | Show Sonarr download queue |
| `radarr_list_movies` | List movies, optionally filtered by name |
| `radarr_queue` | Show Radarr download queue |

### SABnzbd -- Usenet Downloads (3 tools)

Download queue on Atlantis (port 8080).

| Tool | Description |
|------|-------------|
| `sabnzbd_queue` | Show download queue with progress |
| `sabnzbd_pause` | Pause all downloads |
| `sabnzbd_resume` | Resume downloads |

### SSH -- Remote Execution (1 tool)

Key-based SSH to 17 homelab hosts via `~/.ssh/config`.

| Tool | Description |
|------|-------------|
| `ssh_exec` | Run a shell command on any allowed host (default 30s timeout) |

Allowed hosts: atlantis, calypso, setillo, setillo-root, nuc, homelab-vm, rpi5, pi-5, matrix-ubuntu, moon, olares, guava, pve, seattle, seattle-tailscale, gl-mt3000, gl-be3600, jellyfish.

### Filesystem -- Local File Operations (3 tools)

Restricted to `/home/homelab` and `/tmp`.

| Tool | Description |
|------|-------------|
| `fs_read` | Read a file (max 1MB) |
| `fs_write` | Write content to a file |
| `fs_list` | List directory contents |

### Utilities (2 tools)

| Tool | Description |
|------|-------------|
| `check_url` | HTTP health check with expected status code |
| `send_notification` | Push notification via ntfy (homelab-alerts topic) |

## Error Handling

All 64 tool functions are wrapped with the `@_safe` decorator:

```python
@mcp.tool()
@_safe
def some_tool() -> str:
    ...
```

If a tool raises any exception (network timeout, HTTP 500, SSH failure, etc.), `@_safe` catches it and returns an error string like:

```
Error in list_stacks: ConnectTimeout: timed out
```

This prevents the MCP server process from crashing, which previously caused Claude Code to lose the MCP connection mid-session.