7.6 KiB
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
pip install -r requirements.txt
The server runs as a stdio MCP server, configured in Claude Code's project settings:
{
"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
@_safedecorator -- 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:
@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.