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
@_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:

@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.