homelab

The Homelab MCP server provides a unified, single-process MCP instance that exposes a suite of tools for managing and monitoring your homelab infrastructure. Built on the FastMCP framework, it consolidates multiple service controllers (e.g., Docker/Podman containers, network checks, and other infrastructure monitors) into a namespaced set of commands that Claude Desktop can discover and invoke. This unified approach simplifies deployment and gives you a single entry point to access all MCP tools, with consistent naming and health checks. Once running, you can use tools like docker_get_containers, ping_host, and other service-specific commands through Claude, enabling automated checks, status queries, and remediation workflows across your homelab devices and services.

Prerequisites:

• Python 3.10+ and pip
• A compatible operating environment (Windows, macOS, or Linux)
• Access to the Homelab MCP repository and dependencies

Step-by-step installation:

1. Install Python dependencies for the project (from the repository root):

pip install -r requirements.txt

2. Ensure you have the unified MCP script available at the expected path. If you downloaded the project, locate homelab_unified_mcp.py and note its full path.

3. Run the unified MCP server:

python C:\Path\To\Homelab-MCP\homelab_unified_mcp.py

4. (Optional) If deploying via Docker (per project guidance), pull the image and compose as directed in the README. For native development, you can also run individual servers if you prefer a per-service approach.

5. Configure Claude Project Instructions as needed to reflect your network topology and to keep sensitive data private (e.g., API keys, internal hostnames).

Tips and considerations:

• Keep your .env file secure and do not commit it to version control; it may contain API keys and credentials.
• If you choose the unified server deployment, all tools are namespaced under the single process (e.g., docker_get_containers, ping_host). For legacy, per-service deployment, tool names may differ.
• For production, prefer Docker deployments as they simplify dependencies and provide isolation, but ensure Docker access is secured and not exposed to the internet.
• Review MIGRATION_V3.md for guidance if you are migrating from v2.x or adopting the unified server approach.
• Regularly check security guidelines in SECURITY.md and rotate API keys per service as recommended.