Skip to content

Version 2.0.0 - Containerized Deployment with Unified Server

Choose a tag to compare

View all tags
@bjeans bjeans released this 31 Oct 00:52
· 108 commits to main since this release
v2.0.0
1659781
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

🎉 Homelab MCP v2.0.0 - Production Release

Overview

Homelab MCP v2.0.0 introduces a major architectural update with containerized deployment and a unified MCP server. This release brings production-ready Docker support with automatic mode detection and marketplace compatibility.

✨ Key Features

🐳 Containerized Deployment

  • Full Docker support with Dockerfile, docker-compose.yml, and .dockerignore
  • Non-root user security (mcpuser UID 1000)
  • Built-in health checks for production deployments
  • Marketplace-ready configuration via environment variables
  • System dependencies included (iputils-ping for cross-platform support)

🔗 Unified MCP Server

  • Single homelab_unified_mcp.py runs all servers in one process
  • Namespaced tools for unified mode (e.g., docker_get_containers, ping_ping_host)
  • Automatic mode detection (unified vs. legacy)
  • Cleaner logs with no duplicate warnings
  • Better resource efficiency

🏗️ Infrastructure Coverage

  • 7 MCP Servers: Ansible, Docker, Ping, Ollama, Pi-hole, Unifi, UPS
  • 24+ Hosts monitoring capability
  • Cross-platform: Windows, macOS, Linux support verified
  • Dual-mode architecture: All servers support standalone and unified operation

⚙️ Configuration Options

  • Ansible Inventory (Recommended): Centralized configuration with complex host groupings
  • Environment Variables: Simple setup for basic deployments, marketplace-ready

🔒 Security & Production Features

  • Docker non-root user execution
  • Health checks configured for container orchestration
  • Configuration loading via environment variables or Ansible inventory
  • Comprehensive security documentation updated

📦 Available Servers

Unified Mode (Default - All Included)

  • ansible_* - Ansible inventory queries
  • docker_* - Docker/Podman container monitoring
  • ping_* - Network ping utilities
  • ollama_* - Ollama AI model management
  • pihole_* - Pi-hole DNS monitoring
  • unifi_* - Unifi network device monitoring
  • ups_* - UPS/NUT power monitoring

Legacy Mode (Individual Servers)

Set ENABLED_SERVERS environment variable for backward compatibility

Note: MCP Registry Inspector is NOT included in Docker image - development tool only, run directly on host

🚀 Quick Start

Docker Deployment (Recommended)

git clone https://github.com/bjeans/homelab-mcp
cd homelab-mcp

# Build the image
docker build -t homelab-mcp:latest .

# Run with Docker Compose
docker-compose up -d

Direct Installation

pip install -r requirements.txt

# Run unified server
python homelab_unified_mcp.py

# Or run individual server (legacy)
python docker_mcp_podman.py

📚 Documentation

🔄 Migration from v1.x

If you're upgrading from v1.x, see MIGRATION.md for guidance on:

  • Tool name changes in unified mode
  • Configuration migration
  • Legacy mode compatibility

🐛 What's Fixed

  • Docker MCP initialization in unified mode
  • Configuration loading in unified server
  • Inconsistent logging across MCP servers
  • Empty inventory handling in ping server

📈 Infrastructure Tested

  • 7 MCP servers fully integrated
  • Tested with 24+ hosts across multiple services
  • Docker Engine 20.10+ and Docker Compose 2.0+
  • Windows, macOS, and Linux environments verified

🛣️ Roadmap

  • Grafana dashboard integration
  • Home Assistant integration
  • Kubernetes deployment support
  • Enhanced monitoring and alerting features

💡 Community

📄 License

MIT License - See LICENSE for details

Thank you for using Homelab MCP! This release represents a major milestone in bringing production-grade infrastructure automation to Claude Desktop. 🚀

Assets 2
Loading