Installation
Content Details
Alternatives
Installation
{
"mcpServers": {
"homelab-unified": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\homelab_unified_mcp.py"]
}
}
}
{
"mcpServers": {
"docker": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\docker_mcp_podman.py"]
},
"ollama": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\ollama_mcp.py"]
}
}
}
{
"mcpServers": {
"homelab-unified": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\homelab_unified_mcp.py"],
"env": {
"ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
}
}
}
}
{
"mcpServers": {
"docker": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\docker_mcp_podman.py"],
"env": {
"ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
}
},
"ollama": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\ollama_mcp.py"],
"env": {
"ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
}
},
"pihole": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\pihole_mcp.py"],
"env": {
"ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
}
},
"unifi": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\unifi_mcp_optimized.py"],
"env": {
"ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
}
},
"ping": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\ping_mcp_server.py"],
"env": {
"ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
}
},
"ups-monitor": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\ups_mcp_server.py"],
"env": {
"ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
}
}
}
}
{
"mcpServers": {
"homelab-unified": {
"command": "docker",
"args": ["exec", "-i", "homelab-mcp", "python", "homelab_unified_mcp.py"]
}
}
}
{
"mcpServers": {
"homelab-docker": {
"command": "docker",
"args": ["exec", "-i", "homelab-mcp-docker", "python", "docker_mcp_podman.py"]
},
"homelab-ping": {
"command": "docker",
"args": ["exec", "-i", "homelab-mcp", "python", "ping_mcp_server.py"]
}
}
}๐ Homelab MCP Servers
A collection of Model Context Protocol (MCP) servers for managing and monitoring your homelab infrastructure through Claude Desktop.
๐ Quick Start
1. Clone the repository
git clone https://github.com/bjeans/homelab-mcp
cd homelab-mcp
2. Install security checks (recommended)
# Install pre-push git hook for automatic security validation
python helpers/install_git_hook.py
3. Set up configuration files
Environment variables:
# Windows
copy .env.example .env
# Linux/Mac
cp .env.example .env
Edit .env with your actual values:
# Windows
notepad .env
# Linux/Mac
nano .env
Ansible inventory (if using):
# Windows
copy ansible_hosts.example.yml ansible_hosts.yml
# Linux/Mac
cp ansible_hosts.example.yml ansible_hosts.yml
Edit with your infrastructure details. Project instructions:
# Windows
copy PROJECT_INSTRUCTIONS.example.md PROJECT_INSTRUCTIONS.md
# Linux/Mac
cp PROJECT_INSTRUCTIONS.example.md PROJECT_INSTRUCTIONS.md
Customize with your network topology and servers. AI development guide customizations (optional):
# Windows
copy CLAUDE_CUSTOM.example.md CLAUDE_CUSTOM.md
# Linux/Mac
cp CLAUDE_CUSTOM.example.md CLAUDE_CUSTOM.md
Customize with your actual server names and infrastructure details. This file is gitignored and allows Claude to understand your specific homelab setup. See CLAUDE.md for more information about local customizations.
4. Install Python dependencies
pip install -r requirements.txt
5. Add to Claude Desktop config
Config file location:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
Option A: Unified Server (Recommended) Single entry for all homelab servers:
{
"mcpServers": {
"homelab-unified": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\homelab_unified_mcp.py"],
"env": {
"ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
}
}
}
}
Note: The unified server includes 7 MCP servers: Ansible, Docker/Podman, Ollama, Pi-hole, Unifi, UPS, and Ping. The deprecated mcp-registry-inspector is not included.
Option B: Individual Servers (Legacy) Separate entry for each server:
{
"mcpServers": {
"docker": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\docker_mcp_podman.py"],
"env": {
"ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
}
},
"ollama": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\ollama_mcp.py"],
"env": {
"ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
}
},
"pihole": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\pihole_mcp.py"],
"env": {
"ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
}
},
"unifi": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\unifi_mcp_optimized.py"],
"env": {
"ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
}
},
"ping": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\ping_mcp_server.py"],
"env": {
"ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
}
},
"ups-monitor": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\ups_mcp_server.py"],
"env": {
"ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
}
}
}
}
Note: Tool names differ between modes. See MIGRATION.md for details. The deprecated mcp-registry-inspector has been removed from this example. Ansible MCP server integration is tracked in #39.
6. Restart Claude Desktop
7. Add project instructions to Claude
- Copy the contents of your customized
PROJECT_INSTRUCTIONS.md - Paste into your Claude project's "Project instructions" field
- This gives Claude comprehensive context about your MCP capabilities
โจ Features
- Dynamic Tool Parameter Enums: When configuring Ansible inventory, Claude Desktop will automatically display infrastructure options in dropdown menus, eliminating the need to guess hostnames or group names.
- Multiple Deployment Options: Version 2.2.0 offers flexible deployment with two modes (unified server and individual servers) and two methods (Docker container and native Python installation).
- Comprehensive Server Support: Includes servers for managing Docker/Podman containers, Ollama AI models, Pi-hole DNS, Unifi network, Ansible inventory, network connectivity, and UPS monitoring.
- Security Checks: The project includes automated security validation to prevent accidental exposure of sensitive data.
๐ฆ Installation
Deployment Options
Version 2.2.0 offers flexible deployment with two modes and two methods:
Deployment Modes
Choose how your MCP servers are organized:
1. Unified Server (Recommended)
Run all MCP servers in a single process with namespaced tools. This is the recommended approach for new installations and required for Docker deployments.
{
"mcpServers": {
"homelab-unified": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\homelab_unified_mcp.py"]
}
}
}
Advantages:
- โ Single configuration entry
- โ One Python process for all servers
- โ Cleaner logs (no duplicate warnings)
- โ
All tools namespaced (e.g.,
docker_get_containers,ping_ping_host) - โ Required for Docker deployments
- โ Built-in health checks
- โ Production-ready containerization
2. Individual Servers (Legacy, Fully Supported)
Run each MCP server as a separate process. This mode remains fully supported for backward compatibility and only available with native Python installation.
{
"mcpServers": {
"docker": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\docker_mcp_podman.py"]
},
"ollama": {
"command": "python",
"args": ["C:\\Path\\To\\Homelab-MCP\\ollama_mcp.py"]
}
}
}
Advantages:
- โ Granular control over each server
- โ Can enable/disable servers individually
- โ
Original tool names (e.g.,
get_docker_containers,ping_host) - โ Backward compatible with v1.x
Note: Tool names differ between modes. See MIGRATION.md for detailed migration instructions and tool name changes.
Deployment Methods
Choose how to install and run the servers:
1. Docker Container (Recommended for Production)
Pre-built images available on Docker Hub for immediate deployment. See ๐ณ Docker Deployment for full setup instructions. Quick Start:
docker pull bjeans/homelab-mcp:latest
docker-compose up -d
Advantages:
- โ No Python environment setup required
- โ Pre-built, tested images
- โ Automatic updates with image pulls
- โ Multi-platform support (amd64, arm64)
- โ Simplified configuration
- โ Production-grade containerization
Limitations:
- Unified server mode only
- mcp-registry-inspector not available (deprecated)
2. Native Python Installation (Development & Legacy)
Install Python dependencies directly and run servers from source. See ๐ฆ Installation for full setup instructions. Quick Start:
pip install -r requirements.txt
python homelab_unified_mcp.py
Advantages:
- โ Full access to source code
- โ Easy debugging and development
- โ Supports both unified and individual server modes
- โ Can run on any Python-compatible platform
Requirements:
- Python 3.10+ with pip
- Manual dependency management
- Environment configuration via .env file
Migration Guide: See MIGRATION.md for detailed instructions on switching between modes or methods.
๐ป Usage Examples
Dynamic Tool Parameter Enums
When you configure Ansible inventory, Claude Desktop will automatically show your infrastructure options in dropdown menus. What gets auto-populated:
- Ping tools - Your Ansible groups appear in dropdown menus
- Docker tools - Your Docker/Podman hosts shown in dropdowns
- Ollama tools - Your Ollama server hostnames available for selection
- UPS tools - Your NUT server hostnames shown in dropdowns
How it works:
- Set
ANSIBLE_INVENTORY_PATHin your.envfile - Restart Claude Desktop (required - enums load at startup)
- When using tools, Claude shows your actual infrastructure in dropdown menus instead of requiring manual entry
Important Notes:
- Restart Required: Changes to Ansible inventory require restarting Claude Desktop to update dropdown options
- Performance: Enums generate once at startup - minimal impact even with large inventories (100+ hosts)
- Graceful Degradation: If no Ansible inventory is configured, tools still work - you just won't see dropdown suggestions
Example before/after:
Before: "Which group should I ping?" โ User manually types "webservers" (or guesses)
After: "Which group should I ping?" โ User selects from dropdown: all, docker_hosts, webservers, databases, etc.
Troubleshooting:
- Dropdowns not showing? Verify
ANSIBLE_INVENTORY_PATHis set and restart Claude Desktop - Wrong options showing? Check that your Ansible inventory is up-to-date and restart Claude Desktop
- Performance issues? Enum generation happens once at startup - if slow, check inventory file size and Ansible installation
Docker/Podman Container Manager
Manage Docker and Podman containers across multiple hosts. ๐ Security Warning: Docker/Podman APIs typically use unencrypted HTTP without authentication. See SECURITY.md for required firewall configuration. Tools: Individual server mode:
get_docker_containers- Get containers on a specific hostget_all_containers- Get all containers across all hostsget_container_stats- Get CPU and memory statscheck_container- Check if a specific container is runningfind_containers_by_label- Find containers by labelget_container_labels- Get all labels for a container
Unified server mode (namespaced):
docker_get_containers- Get containers on a specific hostdocker_get_all_containers- Get all containers across all hostsdocker_get_container_stats- Get CPU and memory statsdocker_check_container- Check if a specific container is runningdocker_find_containers_by_label- Find containers by labeldocker_get_container_labels- Get all labels for a container
Configuration Options: Option 1: Using Ansible Inventory (Recommended)
ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml
# Ansible inventory group names (default: docker_hosts, podman_hosts)
# Change these if you use different group names in your ansible_hosts.yml
DOCKER_ANSIBLE_GROUP=docker_hosts
PODMAN_ANSIBLE_GROUP=podman_hosts
Option 2: Using Environment Variables
DOCKER_SERVER1_ENDPOINT=192.168.1.100:2375
DOCKER_SERVER2_ENDPOINT=192.168.1.101:2375
PODMAN_SERVER1_ENDPOINT=192.168.1.102:8080
Ollama AI Model Manager
Monitor and manage Ollama AI model instances across your homelab, plus check your LiteLLM proxy for unified API access.
What's Included
Ollama Monitoring:
- Track multiple Ollama instances across different hosts
- View available models and their sizes
- Check instance health and availability
LiteLLM Proxy Integration:
- LiteLLM provides a unified OpenAI-compatible API across all your Ollama instances
- Enables load balancing and failover between multiple Ollama servers
- Allows you to use OpenAI client libraries with your local models
- The MCP server can verify your LiteLLM proxy is online and responding
Why use LiteLLM?
- Load Balancing: Automatically distributes requests across multiple Ollama instances
- Failover: If one Ollama server is down, requests route to healthy servers
- OpenAI Compatibility: Use any OpenAI SDK/library with your local models
- Centralized Access: Single endpoint (e.g.,
http://192.0.2.10:4000) for all models - Usage Tracking: Monitor which models are being used most
Tools:
get_ollama_status- Check status of all Ollama instances and model countsget_ollama_models- Get detailed model list for a specific hostget_litellm_status- Verify LiteLLM proxy is online and responding
Configuration Options: Option 1: Using Ansible Inventory (Recommended)
ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml
OLLAMA_PORT=11434 # Default Ollama port
# Ansible inventory group name (default: ollama_servers)
# Change this if you use a different group name in your ansible_hosts.yml
OLLAMA_INVENTORY_GROUP=ollama_servers
# LiteLLM Configuration
LITELLM_HOST=192.168.1.100 # Host running LiteLLM proxy
LITELLM_PORT=4000 # LiteLLM proxy port (default: 4000)
Option 2: Using Environment Variables
# Ollama Instances
OLLAMA_SERVER1=192.168.1.100
OLLAMA_SERVER2=192.168.1.101
OLLAMA_WORKSTATION=192.168.1.150
# LiteLLM Proxy
LITELLM_HOST=192.168.1.100
LITELLM_PORT=4000
Setting Up LiteLLM (Optional): If you want to use LiteLLM for unified access to your Ollama instances:
- Install LiteLLM on one of your servers:
pip install litellm[proxy]
- Create configuration (
litellm_config.yaml):
model_list:
- model_name: llama3.2
litellm_params:
model: ollama/llama3.2
api_base: http://server1:11434
- model_name: llama3.2
litellm_params:
model: ollama/llama3.2
api_base: http://server2:11434
router_settings:
routing_strategy: usage-based-routing
- Start LiteLLM proxy:
litellm --config litellm_config.yaml --port 4000
- Use the MCP tool to verify it's running:
- In Claude: "Check my LiteLLM proxy status"
Example Usage:
- "What Ollama instances do I have running?"
- "Show me all models on my Dell-Server"
- "Is my LiteLLM proxy online?"
- "How many models are available across all servers?"
Pi-hole DNS Manager
Monitor Pi-hole DNS statistics and status.
๐ Security Note: Store Pi-hole API keys securely in .env file. Generate unique keys per instance.
Tools:
get_pihole_stats- Get DNS statistics from all Pi-hole instancesget_pihole_status- Check which Pi-hole instances are online
Configuration Options: Option 1: Using Ansible Inventory (Recommended)
ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml
# Ansible inventory group name (default: PiHole)
# Change this if you use a different group name in your ansible_hosts.yml
PIHOLE_ANSIBLE_GROUP=PiHole
# API keys still required in .env:
PIHOLE_API_KEY_SERVER1=your-api-key-here
PIHOLE_API_KEY_SERVER2=your-api-key-here
Option 2: Using Environment Variables
PIHOLE_API_KEY_SERVER1=your-api-key
PIHOLE_API_KEY_SERVER2=your-api-key
PIHOLE_SERVER1_HOST=pihole1.local
PIHOLE_SERVER1_PORT=80
PIHOLE_SERVER2_HOST=pihole2.local
PIHOLE_SERVER2_PORT=8053
Getting Pi-hole API Keys:
- Web UI: Settings โ API โ Show API Token
- Or generate new:
pihole -a -pon Pi-hole server
Unifi Network Monitor
Monitor Unifi network infrastructure and clients with caching for performance. ๐ Security Note: Use a dedicated API key with minimal required permissions. Tools:
get_network_devices- Get all network devices (switches, APs, gateways)get_network_clients- Get all active network clientsget_network_summary- Get network overviewrefresh_network_data- Force refresh from controller (bypasses cache)
Configuration:
UNIFI_API_KEY=your-unifi-api-key
UNIFI_HOST=192.168.1.1
Note: Data is cached for 5 minutes to improve performance. Use refresh_network_data to force update.
Ansible Inventory Inspector
Query Ansible inventory information (read-only). Available in both unified and standalone modes.
Unified Mode Tools (with ansible_ prefix):
ansible_get_all_hosts- Get all hosts in inventoryansible_get_all_groups- Get all groupsansible_get_host_details- Get detailed host informationansible_get_group_details- Get detailed group informationansible_get_hosts_by_group- Get hosts in specific groupansible_search_hosts- Search hosts by pattern or variableansible_get_inventory_summary- High-level inventory overviewansible_reload_inventory- Reload inventory from disk
Standalone Mode Tools (without prefix):
get_all_hosts- Get all hosts in inventoryget_all_groups- Get all groupsget_host_details- Get detailed host informationget_group_details- Get detailed group informationget_hosts_by_group- Get hosts in specific groupsearch_hosts- Search hosts by pattern or variableget_inventory_summary- High-level inventory overviewreload_inventory- Reload inventory from disk
Configuration:
ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml
Deployment:
- โ Available in unified server mode
- โ Available in Docker deployments
- โ
Available in standalone mode:
python ansible_mcp_server.py
Ping Network Connectivity Monitor
Test network connectivity and host availability using ICMP ping across your infrastructure. Why use this?
- Quick health checks during outages or after power events
- Verify which hosts are reachable before querying service-specific MCPs
- Simple troubleshooting tool to identify network issues
- Baseline connectivity testing for your infrastructure
Tools:
ping_host- Ping a single host by name (resolved from Ansible inventory)ping_group- Ping all hosts in an Ansible group concurrentlyping_all- Ping all infrastructure hosts concurrentlylist_groups- List available Ansible groups for ping operations
Features:
- โ Cross-platform support - Works on Windows, Linux, and macOS
- โ Ansible integration - Automatically resolves hostnames/IPs from inventory
- โ Concurrent pings - Test multiple hosts simultaneously for faster results
- โ Detailed statistics - RTT min/avg/max, packet loss percentage
- โ Customizable - Configure timeout and packet count
- โ
No dependencies - Uses system
pingcommand (no extra libraries needed)
Configuration:
ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml
# No additional API keys required!
Example Usage:
- "Ping server1.example.local"
- "Check connectivity to all Pi-hole servers"
- "Ping all Ubuntu_Server hosts"
- "Test connectivity to entire infrastructure"
- "What groups can I ping?"
When to use:
- After power outages - Quickly identify which hosts came back online
- Before service checks - Verify host is reachable before checking specific services
- Network troubleshooting - Isolate connectivity issues from service issues
- Health monitoring - Regular checks to ensure infrastructure availability
UPS Monitoring (Network UPS Tools)
Monitor UPS (Uninterruptible Power Supply) devices across your infrastructure using Network UPS Tools (NUT) protocol. Why use this?
- Real-time visibility into power infrastructure status
- Proactive alerts before battery depletion during outages
- Monitor multiple UPS devices across different hosts
- Track battery health and runtime estimates
- Essential for critical infrastructure planning
Tools:
get_ups_status- Check status of all UPS devices across all NUT serversget_ups_details- Get detailed information for a specific UPS deviceget_battery_runtime- Get battery runtime estimates for all UPS devicesget_power_events- Check for recent power events (on battery, low battery)list_ups_devices- List all UPS devices configured in inventoryreload_inventory- Reload Ansible inventory after changes
Features:
- โ NUT protocol support - Uses Network UPS Tools standard protocol (port 3493)
- โ Ansible integration - Automatically discovers UPS from inventory
- โ Multiple UPS per host - Support for servers with multiple UPS devices
- โ Battery monitoring - Track charge level, runtime remaining, load percentage
- โ Power event detection - Identify when UPS switches to battery or low battery
- โ Cross-platform - Works with any NUT-compatible UPS (TrippLite, APC, CyberPower, etc.)
- โ Flexible auth - Optional username/password authentication
Configuration: Option 1: Using Ansible Inventory (Recommended)
ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml
# Default NUT port (optional, defaults to 3493)
NUT_PORT=3493
# NUT authentication (optional - only if your NUT server requires it)
NUT_USERNAME=monuser
NUT_PASSWORD=secret
Ansible inventory example:
nut_servers:
hosts:
dell-server.example.local:
ansible_host: 192.168.1.100
nut_port: 3493
ups_devices:
- name: tripplite
description: "TrippLite SMART1500LCDXL"
Option 2: Using Environment Variables
NUT_PORT=3493
NUT_USERNAME=monuser
NUT_PASSWORD=secret
Prerequisites:
- Install NUT on servers with UPS devices:
# Debian/Ubuntu
sudo apt install nut nut-client nut-server
# RHEL/Rocky/CentOS
sudo dnf install nut nut-client
- Configure NUT daemon (
/etc/nut/ups.conf):
[tripplite]
driver = usbhid-ups
port = auto
desc = "TrippLite SMART1500LCDXL"
- Enable network monitoring (
/etc/nut/upsd.conf):
LISTEN 0.0.0.0 3493
- Configure access (
/etc/nut/upsd.users):
[monuser]
password = secret
upsmon master
- Start NUT services:
sudo systemctl enable nut-server nut-client
sudo systemctl start nut-server nut-client
Example Usage:
- "What's the status of all my UPS devices?"
- "Show me battery runtime for the Dell server UPS"
- "Check for any power events"
- "Get detailed info about the TrippLite UPS"
- "List all configured UPS devices"
When to use:
- After power flickers - Verify UPS devices handled the event properly
- Before maintenance - Check battery levels and estimated runtime
- Regular monitoring - Track UPS health and battery condition
- Capacity planning - Understand how long systems can run on battery
Common UPS Status Codes:
OL- Online (normal operation, AC power present)OB- On Battery (power outage, running on battery)LB- Low Battery (critically low battery, shutdown imminent)CHRG- Charging (battery is charging)RB- Replace Battery (battery needs replacement)
๐ Documentation
This project includes several documentation files for different audiences:
- README.md (this file) - Installation, setup, and usage guide
- MIGRATION.md - Migration guide for v2.0 unified server
- PROJECT_INSTRUCTIONS.md - Copy into Claude project instructions for AI context
- CLAUDE.md - Developer guide for AI assistants and contributors
- SECURITY.md - Security policies and best practices
- CONTRIBUTING.md - How to contribute to this project
- CHANGELOG.md - Version history and changes
๐ฅ For End Users: Follow this README + copy PROJECT_INSTRUCTIONS.md to Claude ๐ Migrating from v1.x? See MIGRATION.md for unified server migration ๐ค For AI Assistants: Read CLAUDE.md for complete development context ๐ง For Contributors: Start with CONTRIBUTING.md and CLAUDE.md
๐ง Technical Details
Automated Security Checks
This project includes automated security validation to prevent accidental exposure of sensitive data: Install the pre-push git hook (recommended):
# From project root
python helpers/install_git_hook.py
What it does:
- Automatically runs
helpers/pre_publish_check.pybefore every git push - Blocks pushes that contain potential secrets or sensitive data
- Protects against accidentally committing API keys, passwords, or personal information
Manual security check:
# Run security validation manually
python helpers/pre_publish_check.py
Bypass security check (use with extreme caution):
# Only when absolutely necessary
git push --no-verify
Critical Security Practices
Configuration Files:
- โ
DO use
.env.exampleas a template - โ
DO keep
.envfile permissions restrictive (chmod 600on Linux/Mac) - โ NEVER commit
.envto version control - โ NEVER commit
ansible_hosts.ymlwith real infrastructure - โ NEVER commit
PROJECT_INSTRUCTIONS.mdwith real network topology
API Security:
- โ DO use unique API keys for each service
- โ DO rotate API keys regularly (every 90 days recommended)
- โ DO use strong, randomly-generated keys (32+ characters)
- โ NEVER expose Docker/Podman APIs to the internet
- โ NEVER reuse API keys between environments
Network Security:
- โ DO use firewall rules to restrict API access
- โ DO implement VLAN segmentation
- โ DO enable TLS/HTTPS where possible
- โ NEVER expose management interfaces publicly
For detailed security guidance, see SECURITY.md
๐ณ Docker Deployment (Alternative)
Run the MCP servers in Docker containers for easier distribution, isolation, and production deployment. Docker Hub: bjeans/homelab-mcp
Quick Start with Docker Hub (Easiest)
Pre-built images are automatically published to Docker Hub with multi-platform support (amd64/arm64):
# Pull the latest image
docker pull bjeans/homelab-mcp:latest
# Run with your Ansible inventory
docker run -d \
--name homelab-mcp \
--network host \
-v $(pwd)/ansible_hosts.yml:/config/ansible_hosts.yml:ro \
bjeans/homelab-mcp:latest
# Or use a specific commit
docker pull bjeans/homelab-mcp:main-17bae01
Available on Docker Hub: https://hub.docker.com/r/bjeans/homelab-mcp/tags Currently available tags:
latest- Latest stable release from main branch (recommended)edge- Latest development build from main branchmain-<git-sha>- Specific commit builds for traceability (e.g.,main-17bae01)
Semantic version tags (available after release):
- Version tags like
2.2.0,2.2,2will be created when thev2.2.0Git release is published - Until then, use
latestfor the most recent stable build
Multi-platform support:
linux/amd64- x86_64 servers and workstationslinux/arm64- Raspberry Pi, ARM-based systems
Build from Source (Advanced)
Build the image locally if you need to customize:
# Pull the pre-built image from Docker Hub (recommended)
docker pull bjeans/homelab-mcp:latest
# Run with Docker Compose (recommended for production)
docker-compose up -d
# Or run unified server directly
docker run -d \
--name homelab-mcp \
--network host \
-v $(pwd)/ansible_hosts.yml:/config/ansible_hosts.yml:ro \
bjeans/homelab-mcp:latest
Building from source (optional):
# Clone and navigate to repository
git clone https://github.com/bjeans/homelab-mcp
cd homelab-mcp
# Build the image locally
docker build -t homelab-mcp:latest .
Docker Features
2.0.0 Docker Improvements:
- โ Unified MCP server as default entrypoint (all 7 servers in one container)
- โ Automatic unified mode detection (no ENABLED_SERVERS needed)
- โ Built-in health checks (HEALTHCHECK configured)
- โ Non-root user security (mcpuser UID 1000)
- โ Proper signal handling and clean shutdown
- โ Optimized layer caching for faster rebuilds
- โ System dependencies included (iputils-ping for cross-platform support)
Configuration Methods
Method 1: Ansible Inventory (Recommended)
# Create your ansible_hosts.yml with infrastructure details
# Then mount as volume:
docker run -d \
--name homelab-mcp \
--network host \
-v $(pwd)/ansible_hosts.yml:/config/ansible_hosts.yml:ro \
bjeans/homelab-mcp:latest
Method 2: Environment Variables (Marketplace Ready)
docker run -d \
--name homelab-mcp \
--network host \
-e DOCKER_SERVER1_ENDPOINT=192.168.1.100:2375 \
-e DOCKER_SERVER1_NAME=Local-Docker \
-e OLLAMA_SERVER1_ENDPOINT=192.168.1.100:11434 \
bjeans/homelab-mcp:latest
Legacy Mode: Individual Servers (Docker)
For backward compatibility, you can still run individual servers by setting ENABLED_SERVERS:
docker run -d \
--name homelab-mcp-docker \
--network host \
-e ENABLED_SERVERS=docker \
-v $(pwd)/ansible_hosts.yml:/config/ansible_hosts.yml:ro \
bjeans/homelab-mcp:latest
Available Servers
Unified Mode (Default):
- โ All 7 servers in one process: Ansible, Docker, Ping, Ollama, Pi-hole, Unifi, UPS
- โ
Namespaced tools (e.g.,
ansible_get_all_hosts,docker_get_containers,ups_get_ups_status) - โ Single configuration entry
- โ Built-in health checks
Legacy Mode (Set ENABLED_SERVERS):
- โ
ansible- Ansible inventory queries - โ
docker- Docker/Podman container management - โ
ping- Network ping utilities - โ
ollama- Ollama AI model management - โ
pihole- Pi-hole DNS statistics - โ
unifi- Unifi network device monitoring - โ
ups- UPS/NUT power monitoring
Docker Configuration
Two configuration methods supported:
- Ansible Inventory (Recommended) - Mount as volume
- Environment Variables - Pass via Docker
-eflags
See DOCKER.md for comprehensive Docker deployment guide including:
- Detailed setup instructions
- Network configuration options
- Security best practices
- Claude Desktop integration
- Troubleshooting common issues
Integration with Claude Desktop
Unified Mode (Recommended):
{
"mcpServers": {
"homelab-unified": {
"command": "docker",
"args": ["exec", "-i", "homelab-mcp", "python", "homelab_unified_mcp.py"]
}
}
}
Legacy Mode (Individual Servers):
{
"mcpServers": {
"homelab-docker": {
"command": "docker",
"args": ["exec", "-i", "homelab-mcp-docker", "python", "docker_mcp_podman.py"]
},
"homelab-ping": {
"command": "docker",
"args": ["exec", "-i", "homelab-mcp", "python", "ping_mcp_server.py"]
}
}
}
Important: Use docker exec -i (not -it) for proper MCP stdio communication.
Testing Docker Containers
Quick verification test (using environment variables - marketplace ready):
# Test Unified Server
docker run --rm --network host \
-e DOCKER_SERVER1_ENDPOINT=localhost:2375 \
-e OLLAMA_SERVER1_ENDPOINT=localhost:11434 \
bjeans/homelab-mcp:latest
# Test Individual Server (legacy)
docker run --rm --network host \
-e ENABLED_SERVERS=ping \
bjeans/homelab-mcp:latest
Docker Compose testing:
docker-compose up -d
docker-compose logs -f
For comprehensive Docker deployment guide, see DOCKER.md.
๐ License
MIT License - See LICENSE file for details Copyright (c) 2025 Barnaby Jeans
๐ค Contributing
Contributions are welcome! Please see CONTRIBUTING.md for detailed guidelines.
For AI Assistants & Developers
๐ Read CLAUDE.md first - This file contains:
- Complete project architecture and development patterns
- Security requirements and common pitfalls to avoid
- Specific workflows for adding features and fixing bugs
- AI assistant-specific guidance for working with this codebase
Quick Start for Contributors
- Install security git hook (
python helpers/install_git_hook.py) - Review security guidelines in SECURITY.md
- No sensitive data in commits (hook will block automatically)
- All configuration uses environment variables or Ansible
- Update documentation for any changes
- Test thoroughly with real infrastructure
Pull Request Process
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Test with your homelab setup
- Update README and other docs as needed
- Commit with clear messages (
git commit -m 'Add amazing feature') - Push to your fork (
git push origin feature/amazing-feature) - Open a Pull Request
Code Review Criteria
- Security best practices followed
- No hardcoded credentials or IPs
- Proper error handling
- Code follows existing patterns
- Documentation is clear and complete
- Changes are tested
๐ Acknowledgments
- Anthropic for Claude and MCP
- The homelab community for inspiration
- Contributors and testers
๐ Support
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Security: See SECURITY.md for reporting vulnerabilities
Remember: This project handles critical infrastructure. Always prioritize security and test changes in a safe environment first!









