Back to Home
bjeans icon

homelab-mcp

Verified Safe

by bjeans

Overview

Manage and monitor homelab infrastructure components (Docker, DNS, Network, AI, UPS, Ansible) through Claude Desktop.

Installation

Run Command
docker run -d --name homelab-mcp --network host -v $(pwd)/ansible_hosts.yml:/config/ansible_hosts.yml:ro bjeans/homelab-mcp:latest

Environment Variables

  • ANSIBLE_INVENTORY_PATH
  • UNIFI_HOST
  • UNIFI_API_KEY
  • PIHOLE_API_KEY_SERVER1
  • OLLAMA_SERVER1
  • LITELLM_HOST
  • DOCKER_SERVER1_ENDPOINT
  • NUT_USERNAME
  • NUT_PASSWORD

Security Notes

The project demonstrates a high commitment to security. It includes automated pre-push Git hooks (`pre_publish_check.py`) to prevent accidental commits of sensitive data (private IPs, API keys, credentials) and provides extensive documentation (`SECURITY.md`, `CLAUDE.md`, `README.md`) on secure configuration, network isolation, and API access best practices. Environment variables are strictly allowlisted (`mcp_config_loader.py`) and recommended over hardcoding. However, it relies on external services (e.g., Docker/Podman APIs, NUT) that may have inherently insecure defaults (unencrypted HTTP, no authentication) if not properly configured with external firewalls or TLS. A 'KNOWN ISSUE' regarding API keys potentially being visible in process lists for `unifi_exporter.py` is acknowledged but is a minor flaw in an otherwise robust security posture. The `network_mode: host` in Docker Compose, while practical for homelabs, increases local network exposure, which is explicitly warned about.

Similar Servers

Stats

Interest Score34
Security Score8
Cost ClassLow
Avg Tokens300
Stars3
Forks1
Last Update2025-12-07

Tags

HomelabInfrastructureMonitoringAutomationClaude Desktop