Sanitized mirror from private repository - 2026-04-06 03:11:43 UTC
This commit is contained in:
Gitea Mirror Bot
217
scripts/homelab-mcp/README.md
Normal file
217
scripts/homelab-mcp/README.md
Normal file
@@ -0,0 +1,217 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user