Homelab MCP Servers

Model Context Protocol (MCP) servers for managing homelab infrastructure through Claude Desktop.

A collection of Model Context Protocol (MCP) servers for managing and monitoring your homelab infrastructure through Claude Desktop.

🔒 Security Notice

⚠️ IMPORTANT: Please read SECURITY.md before deploying this project.

This project interacts with critical infrastructure (Docker APIs, DNS, network devices). Improper configuration can expose your homelab to security risks.

Key Security Requirements:

NEVER expose Docker/Podman APIs to the internet - Use firewall rules to restrict access
Keep .env file secure - Contains API keys and should never be committed
Use unique API keys - Generate separate keys for each service
Review network security - Ensure proper VLAN segmentation and firewall rules

See SECURITY.md for comprehensive security guidance.

� Documentation Overview

This project includes several documentation files for different audiences:

README.md (this file) - Installation, setup, and usage guide
MIGRATION_V3.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_V3.md for unified server migration 🤖 For AI Assistants: Read CLAUDE.md for complete development context 🔧 For Contributors: Start with CONTRIBUTING.md and CLAUDE.md

�📖 Important: Configure Claude Project Instructions

After setting up the MCP servers, create your personalized project instructions:

Copy the example template:

hljs language-bash

# Windows
copy PROJECT_INSTRUCTIONS.example.md PROJECT_INSTRUCTIONS.md

# Linux/Mac
cp PROJECT_INSTRUCTIONS.example.md PROJECT_INSTRUCTIONS.md

Edit the file with your actual infrastructure details:

PROJECT_INSTRUCTIONS.md (for Claude Desktop project instructions):
- Replace example IP addresses with your real network addresses
- Add your actual server hostnames
- Customize with your specific services and configurations
- Keep this file private - it contains your network topology
CLAUDE_CUSTOM.md (for AI development work - contributors only):
- Update repository URLs with your actual GitHub repository
- Add your Notion workspace URLs if using task management
- Customize infrastructure references
- Keep this file private - contains your specific URLs and setup
Add to Claude Desktop:
- Open Claude Desktop
- Go to your project settings
- Copy the contents of your customized PROJECT_INSTRUCTIONS.md
- Paste into the "Project instructions" field

What's included:

Detailed MCP server capabilities and usage patterns
Infrastructure overview and monitoring capabilities
Specific commands and tools available for each service
Troubleshooting and development guidance

This README covers installation and basic setup. The project instructions provide Claude with comprehensive usage context.

🎯 Deployment Options

Version 3.0.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.

hljs language-json

{
  "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.

hljs language-json

{
  "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_V3.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:

hljs language-bash

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:

hljs language-bash

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_V3.md for detailed instructions on switching between modes or methods.

⚡ FastMCP Framework (v3.0.0)

Version 3.0.0 uses FastMCP: A modern MCP framework that simplifies server architecture while adding support for multiple transport mechanisms and tool annotations.

What is FastMCP?

FastMCP is a lightweight framework that:

✅ Reduces server code by 38% (1,754 lines eliminated)
✅ Uses simple decorator pattern (@mcp.tool()) for tool definitions
✅ Includes comprehensive tool annotations for behavioral hints
✅ Adds support for HTTP and SSE transports (in addition to stdio)
✅ Auto-generates schemas from Python type hints
✅ Improves code maintainability and makes adding new servers easier

All 39 tools now include MCP annotations (readOnlyHint, idempotentHint, etc.) to help Claude make informed decisions about tool usage.

Transport Options

FastMCP servers can operate using different transport mechanisms:

1. Standard Input/Output (stdio) - Default

The traditional MCP transport used by Claude Desktop. This is the default and recommended option for most users.

hljs language-bash

# Run with stdio (default)
python homelab_unified_mcp.py

# Or explicitly specify stdio transport
python homelab_unified_mcp.py --transport stdio

When to use:

Claude Desktop integration (default mode)
Most common use case
No additional configuration needed

2. HTTP Transport

Run MCP servers as HTTP services for remote or flexible deployment scenarios.

hljs language-bash

# Start server with HTTP transport
python homelab_unified_mcp.py --transport http --host 0.0.0.0 --port 8000

# Test the HTTP endpoint
curl http://localhost:8000/tools

When to use:

Deploying servers remotely
Web-based integrations
Multi-client scenarios
Load balancing requirements

3. Server-Sent Events (SSE) Transport

Stream-based protocol for real-time bidirectional communication.

hljs language-bash

# Start server with SSE transport
python homelab_unified_mcp.py --transport sse --host 0.0.0.0 --port 8000

# Connect via SSE client
curl http://localhost:8000/sse

When to use:

Real-time monitoring applications
Browser-based integrations
Event-driven architectures
Streaming responses

Configuring Claude Desktop with FastMCP

Claude Desktop continues to use stdio transport by default. No configuration changes are required:

hljs language-json

{
  "mcpServers": {
    "homelab-unified": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\homelab_unified_mcp.py"]
    }
  }
}

Migration from v2.2.0

If you're upgrading from v2.2.0:

✅ No breaking changes - Your existing configuration continues to work unchanged
✅ Same functionality - All 7 servers and all tools remain identical
✅ Cleaner code - Internal refactoring produces the same results
✅ New options - Optional HTTP/SSE transports available if needed

No action required - just update and restart Claude Desktop.

🚀 Quick Start

1. Clone the repository

hljs language-bash

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

2. Install security checks (recommended)

hljs language-bash

# Install pre-push git hook for automatic security validation
python helpers/install_git_hook.py

3. Set up configuration files

Environment variables:

hljs language-bash

# Windows
copy .env.example .env

# Linux/Mac
cp .env.example .env

Edit .env with your actual values:

hljs language-bash

# Windows
notepad .env

# Linux/Mac
nano .env

Ansible inventory (if using):

hljs language-bash

# 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:

hljs language-bash

# 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):

hljs language-bash

# 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

hljs language-bash

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:

hljs language-json

{
  "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:

hljs language-json

{
  "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_V3.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

🐳 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):

hljs language-bash

# 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 branch
main-<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, 2 will be created when the v2.2.0 Git release is published
Until then, use latest for the most recent stable build

Multi-platform support:

linux/amd64 - x86_64 servers and workstations
linux/arm64 - Raspberry Pi, ARM-based systems

Build from Source (Advanced)

Build the image locally if you need to customize:

hljs language-bash

# 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):

hljs language-bash

# 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)

hljs language-bash

# 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)

hljs language-bash

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:

hljs language-bash

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 -e flags

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):

hljs language-json

{
  "mcpServers": {
    "homelab-unified": {
      "command": "docker",
      "args": ["exec", "-i", "homelab-mcp", "python", "homelab_unified_mcp.py"]
    }
  }
}

Legacy Mode (Individual Servers):

hljs language-json

{
  "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):

hljs language-bash

# 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:

hljs language-bash

docker-compose up -d
docker-compose logs -f

For comprehensive Docker deployment guide, see DOCKER.md.

📦 Available MCP Servers

✨ Dynamic Tool Parameter Enums (New in v2.1.0)

When you configure Ansible inventory, Claude Desktop will automatically show your infrastructure options in dropdown menus. No more guessing hostnames or group names!

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_PATH in your .env file
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_PATH is 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

MCP Registry Inspector (⚠️ DEPRECATED)

Deprecation Notice (v2.3.0): This tool is deprecated. Claude Desktop now has native file system access, making this MCP server unnecessary. You can simply ask Claude to read your MCP server files or configuration directly.

Replacement: Use Claude's built-in file access:

"Read my claude_desktop_config.json file"
"Show me the source code for docker_mcp_podman.py"
"List all .py files in this directory"

For users with existing configurations: This server will continue to work but will not receive updates. It will be removed from documentation in v3.0.0. Consider removing it from your claude_desktop_config.json.

Legacy Configuration (for reference only)

Tools:

get_claude_config - View Claude Desktop MCP configuration
list_mcp_servers - List all registered MCP servers
list_mcp_directory - Browse MCP development directory
read_mcp_file - Read MCP server source code
write_mcp_file - Write/update MCP server files
search_mcp_files - Search for files by name

Configuration:

hljs language-bash

MCP_DIRECTORY=/path/to/your/Homelab-MCP
CLAUDE_CONFIG_PATH=/path/to/claude_desktop_config.json  # Optional

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 host
get_all_containers - Get all containers across all hosts
get_container_stats - Get CPU and memory stats
check_container - Check if a specific container is running
find_containers_by_label - Find containers by label
get_container_labels - Get all labels for a container

Unified server mode (namespaced):

docker_get_containers - Get containers on a specific host
docker_get_all_containers - Get all containers across all hosts
docker_get_container_stats - Get CPU and memory stats
docker_check_container - Check if a specific container is running
docker_find_containers_by_label - Find containers by label
docker_get_container_labels - Get all labels for a container

Configuration Options:

Option 1: Using Ansible Inventory (Recommended)

hljs language-bash

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

hljs language-bash

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 counts
get_ollama_models - Get detailed model list for a specific host
get_litellm_status - Verify LiteLLM proxy is online and responding

Configuration Options:

Option 1: Using Ansible Inventory (Recommended)

hljs language-bash

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

hljs language-bash

# 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:
hljs language-bash
```
pip install litellm[proxy]
```

Create configuration (litellm_config.yaml):

hljs language-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:

hljs language-bash

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 instances
get_pihole_status - Check which Pi-hole instances are online

Configuration Options:

Option 1: Using Ansible Inventory (Recommended)

hljs language-bash

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

hljs language-bash

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 -p on 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 clients
get_network_summary - Get network overview
refresh_network_data - Force refresh from controller (bypasses cache)

Configuration:

hljs language-bash

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 inventory
ansible_get_all_groups - Get all groups
ansible_get_host_details - Get detailed host information
ansible_get_group_details - Get detailed group information
ansible_get_hosts_by_group - Get hosts in specific group
ansible_search_hosts - Search hosts by pattern or variable
ansible_get_inventory_summary - High-level inventory overview
ansible_reload_inventory - Reload inventory from disk

Standalone Mode Tools (without prefix):

get_all_hosts - Get all hosts in inventory
get_all_groups - Get all groups
get_host_details - Get detailed host information
get_group_details - Get detailed group information
get_hosts_by_group - Get hosts in specific group
search_hosts - Search hosts by pattern or variable
get_inventory_summary - High-level inventory overview
reload_inventory - Reload inventory from disk

Configuration:

hljs language-bash

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 concurrently
ping_all - Ping all infrastructure hosts concurrently
list_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 ping command (no extra libraries needed)

Configuration:

hljs language-bash

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 servers
get_ups_details - Get detailed information for a specific UPS device
get_battery_runtime - Get battery runtime estimates for all UPS devices
get_power_events - Check for recent power events (on battery, low battery)
list_ups_devices - List all UPS devices configured in inventory
reload_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)

hljs language-bash

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:

hljs language-yaml

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

hljs language-bash

NUT_PORT=3493
NUT_USERNAME=monuser
NUT_PASSWORD=secret

Prerequisites:

Install NUT on servers with UPS devices:

hljs language-bash

# 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):

hljs language-ini

[tripplite]
    driver = usbhid-ups
    port = auto
    desc = "TrippLite SMART1500LCDXL"

Enable network monitoring (/etc/nut/upsd.conf):
hljs language-ini
```
LISTEN 0.0.0.0 3493
```
Configure access (/etc/nut/upsd.users):
hljs language-ini
```
[monuser]
    password = secret
    upsmon master
```

Start NUT services:

hljs language-bash

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)

🔒 Security

Automated Security Checks

This project includes automated security validation to prevent accidental exposure of sensitive data:

Install the pre-push git hook (recommended):

hljs language-bash

# From project root
python helpers/install_git_hook.py

What it does:

Automatically runs helpers/pre_publish_check.py before 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:

hljs language-bash

# Run security validation manually
python helpers/pre_publish_check.py

Bypass security check (use with extreme caution):

hljs language-bash

# Only when absolutely necessary
git push --no-verify

Critical Security Practices

Configuration Files:

✅ DO use .env.example as a template
✅ DO keep .env file permissions restrictive (chmod 600 on Linux/Mac)
❌ NEVER commit .env to version control
❌ NEVER commit ansible_hosts.yml with real infrastructure
❌ NEVER commit PROJECT_INSTRUCTIONS.md with 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

📋 Requirements

System Requirements

Python: 3.10 or higher
Claude Desktop: Latest version recommended
Network Access: Connectivity to homelab services

Python Dependencies

Install via requirements.txt:

hljs language-bash

pip install -r requirements.txt

Core dependencies:

mcp - Model Context Protocol SDK
aiohttp - Async HTTP client
pyyaml - YAML parsing for Ansible inventory

Service Requirements

Docker/Podman: API enabled on monitored hosts
Pi-hole: v6+ with API enabled
Unifi Controller: API access enabled
Ollama: Running instances with API accessible
NUT (Network UPS Tools): Installed and configured on hosts with UPS devices
Ansible: Inventory file (optional but recommended)

💻 Compatibility

Tested Platforms

Developed and tested on:

OS: Windows 11
Claude Desktop: Version 0.13.64
Python: Version 3.13.8

Cross-Platform Notes

Windows: Fully tested and supported ✅ macOS: Should work but untested ⚠️ Linux: Should work but untested ⚠️

Known platform differences:

File paths in documentation are Windows-style
Path separators may need adjustment for Unix systems
.env file permissions should be set on Unix (chmod 600 .env)

Contributions for other platforms welcome!

🛠️ Development

📖 First time contributing? Read CLAUDE.md for complete development guidance including architecture patterns, security requirements, and AI assistant workflows.

Getting Started

Install security git hook (required for contributors):
hljs language-bash
```
python helpers/install_git_hook.py
```

Set up development environment:

hljs language-bash

pip install -r requirements.txt
cp .env.example .env
# Edit .env with your test values

Testing MCP Servers Locally

Before submitting a PR, test your MCP server changes locally using the MCP Inspector tool.

Quick start:

hljs language-bash

# MCP Inspector is an optional Node.js tool for interactive testing
# Option 1: Use npx (no installation needed - recommended)
npx @modelcontextprotocol/inspector uv --directory . run <server>_mcp.py

# Option 2: Install globally first (one-time setup)
npm install -g @modelcontextprotocol/inspector
# Then run: mcp-inspector uv --directory . run <server>_mcp.py

This opens a web-based debugger at http://localhost:5173 where you can:

See all available tools for the MCP server
Test each tool with sample arguments
Verify responses are properly formatted
Debug issues before submitting PRs

For detailed testing instructions, see the Testing MCP Servers Locally section in CONTRIBUTING.md.

Helper Scripts

The helpers/ directory contains utility scripts for development and deployment:

install_git_hook.py - Installs git pre-push hook for automatic security checks
pre_publish_check.py - Security validation script (runs automatically via git hook)

Usage:

hljs language-bash

# Install security git hook
python helpers/install_git_hook.py

# Run security check manually  
python helpers/pre_publish_check.py

Project Structure

hljs language-text

Homelab-MCP/
├── MCP Servers (7 production servers)
│   ├── ansible_mcp_server.py      # Ansible inventory queries (integration in progress)
│   ├── docker_mcp_podman.py       # Docker/Podman container monitoring
│   ├── ollama_mcp.py              # Ollama AI model management
│   ├── pihole_mcp.py              # Pi-hole DNS monitoring
│   ├── ping_mcp_server.py         # Network connectivity testing
│   ├── unifi_mcp_optimized.py     # Unifi network device monitoring
│   └── ups_mcp_server.py          # UPS/NUT monitoring
│
├── Unified Server & Core Modules
│   ├── homelab_unified_mcp.py     # Combines all servers (Docker entrypoint)
│   ├── mcp_config_loader.py       # Secure environment variable loading
│   ├── mcp_error_handler.py       # Centralized error handling
│   └── ansible_config_manager.py  # Ansible inventory + enum generation
│
├── Utilities & Deprecated Tools
│   ├── unifi_exporter.py          # Unifi data export utility
│   └── mcp_registry_inspector.py  # MCP file management (⚠️ DEPRECATED v2.3.0)
│
├── Configuration & Examples
│   ├── .env.example               # Configuration template (gitignored)
│   ├── ansible_hosts.example.yml  # Ansible inventory example (gitignored)
│   ├── PROJECT_INSTRUCTIONS.example.md # AI assistant guide template
│   └── CLAUDE_CUSTOM.example.md   # Local customization template (gitignored)
│
├── Documentation
│   ├── README.md                  # This file - user documentation
│   ├── CLAUDE.md                  # AI assistant development guide
│   ├── SECURITY.md                # Security guidelines
│   ├── CONTRIBUTING.md            # Contribution guide
│   ├── CHANGELOG.md               # Version history
│   ├── MIGRATION_V3.md               # Version migration guide
│   ├── CONTEXT_AWARE_SECURITY.md  # Security scanning docs
│   ├── CI_CD_CHECKS.md            # CI/CD automation docs
│   └── LICENSE                    # MIT License
│
├── Docker Deployment
│   ├── Dockerfile                 # Container build configuration
│   ├── docker-compose.yml         # Container orchestration (uses bjeans/homelab-mcp:latest)
│   └── docker-entrypoint.sh       # Container startup script
│
├── Development Tools
│   ├── helpers/
│   │   ├── install_git_hook.py    # Git pre-push hook installer
│   │   ├── pre_publish_check.py   # Security validation
│   │   ├── run_checks.py          # CI/CD check runner
│   │   └── requirements-dev.txt   # Development dependencies
│   ├── requirements.txt           # Production Python dependencies
│   └── .gitignore                 # Git ignore rules

Adding a New MCP Server

Create the server file

hljs language-python

#!/usr/bin/env python3
"""
My Service MCP Server
Description of what it does
"""
import asyncio
from mcp.server import Server
# ... implement tools ...

Add configuration to .env.example

hljs language-bash

# My Service Configuration
MY_SERVICE_HOST=192.168.1.100
MY_SERVICE_API_KEY=your-api-key

Update documentation
- Add server details to this README
- Update PROJECT_INSTRUCTIONS.example.md
- Update CLAUDE.md if adding new patterns or capabilities
- Add security notes if applicable
Test thoroughly
- Test with real infrastructure
- Verify error handling
- Check for sensitive data leaks
- Review security implications

Environment Variables

All MCP servers support two configuration methods:

1. Environment Variables (.env file)

Simple key=value pairs
Loaded automatically by each MCP server
Good for simple setups or testing

2. Ansible Inventory (recommended for production)

Centralized infrastructure definition
Supports complex host groupings
Better for multi-host environments
Set ANSIBLE_INVENTORY_PATH in .env

Coding Standards

Python 3.10+ syntax and features
Async/await for all I/O operations
Type hints where beneficial
Error handling for network operations
Logging to stderr for debugging
Security: Validate inputs, sanitize outputs

Testing Checklist

Before committing changes:

Security git hook installed (python helpers/install_git_hook.py)
Manual security check passes (python helpers/pre_publish_check.py)
No sensitive data in code or commits
Environment variables for all configuration
Error handling for network failures
Logging doesn't expose secrets
Documentation updated
Security implications reviewed
.gitignore updated if needed

🐛 Troubleshooting

MCP Servers Not Appearing in Claude

Check Claude Desktop config:

hljs language-bash

# Windows
type %APPDATA%\Claude\claude_desktop_config.json

# Mac/Linux
cat ~/.config/Claude/claude_desktop_config.json

Verify Python path is correct in config
Restart Claude Desktop completely
Check logs - MCP servers log to stderr

Connection Errors

Docker/Podman API:

hljs language-bash

# Test connectivity
curl http://your-host:2375/containers/json

# Check firewall
netstat -an | grep 2375

Pi-hole API:

hljs language-bash

# Test API key
curl "http://your-pihole/api/stats/summary?sid=YOUR_API_KEY"

Ollama:

hljs language-bash

# Test Ollama endpoint
curl http://your-host:11434/api/tags

Understanding Error Messages

Error Message Format (v2.2.0+):

All MCP servers now provide detailed, actionable error messages in this format:

hljs language-less

✗ [Service] [Error Type] (HTTP Status)

[Specific problem description]

Host: [hostname:port]

→ [Actionable remediation steps]

Technical details: [error details] (timestamp)

Common Error Types:

1. Authentication Failed (401)

Example:

hljs language-bash

✗ Pi-hole Authentication Failed (401)

Invalid API key for pi-hole-1

Host: 192.168.1.5:80

→ Verify PIHOLE_API_KEY_PI_HOLE_1 in .env matches your Pi-hole admin password.
→ You can find/reset this in Pi-hole Settings > API.

How to Fix:

Check your .env file for the correct API key variable
Verify the API key matches the service's admin panel
For Pi-hole: Settings > API > Show API token
For Unifi: Settings > Admins > API > Generate key

2. Connection Failed

Example:

hljs language-vbnet

✗ Unifi Connection Failed

Unable to connect to unifi-controller:443

Host: unifi-controller:443

→ Ensure Unifi controller is running and accessible at unifi-controller:443.
→ Test connectivity: nc -zv unifi-controller 443
→ Check firewall: sudo iptables -L | grep 443

How to Fix:

Verify the service is running: systemctl status [service-name]
Test network connectivity with nc or telnet
Check firewall rules allow access to the port
Verify the hostname/IP is correct in your configuration

3. Timeout Errors

Example:

hljs language-sql

✗ Ollama Timeout

Connection to ollama-1:11434 timed out (after 5s)

Host: ollama-1:11434

→ The service is not responding. Check if Ollama is running and not overloaded.
→ Check service status and logs for performance issues.

How to Fix:

Check if the service is running: systemctl status ollama
Look for performance issues in service logs
Verify network latency: ping [hostname]
Consider increasing timeout values if service is legitimately slow

4. Invalid/Expired Credentials (403)

Example:

hljs language-csharp

✗ Service Authorization Failed (403)

Valid credentials but insufficient permissions

→ Ensure the API key/account has the required permissions for this operation.

How to Fix:

Check account permissions in the service admin panel
Ensure the API key has admin/full access rights
Regenerate API key if permissions were recently changed

5. Unifi Exporter Errors

Before (v2.1.0):

hljs language-javascript

Error: Exporter failed with code 1

After (v2.2.0):

hljs language-vbnet

✗ Unifi Authentication Failed

Invalid Unifi API key for unifi-controller

Host: unifi-controller

→ Verify UNIFI_API_KEY in .env matches the API key from Unifi Settings > Admins > API.
→ Ensure the key has not expired.

Technical details: 401 Unauthorized (at 2025-11-20T10:30:45Z)

How to Fix:

Log into Unifi controller
Navigate to Settings > Admins > API
Verify or regenerate API key
Update UNIFI_API_KEY in .env file
Restart Claude Desktop to reload configuration

6. Service Unavailable (503)

How to Fix:

Check if the service is running
Look for service startup errors in logs
Verify all dependencies are available
Consider restarting the service

Debugging Tips

Enable Detailed Logging:

All errors are logged to stderr with full context. Check Claude Desktop logs:

Windows: %APPDATA%\Claude\logs\
Mac: ~/Library/Logs/Claude/
Linux: ~/.config/Claude/logs/

Test API Endpoints Directly:

Use curl or httpie to test API endpoints outside of MCP:

hljs language-bash

# Pi-hole
curl "http://pi-hole:80/api/stats/summary?sid=YOUR_API_KEY"

# Docker
curl http://docker-host:2375/containers/json

# Unifi (requires SSL and API key)
curl -k -H "X-API-KEY: YOUR_KEY" https://unifi:443/api/stat/sta

# Ollama
curl http://ollama:11434/api/tags

# NUT (Network UPS Tools)
telnet nut-server 3493
> LIST UPS

Check Configuration:

hljs language-bash

# Verify .env file exists and is readable
ls -la .env

# Check for syntax errors in .env
cat .env | grep -v '^#' | grep -v '^$'

# Verify Ansible inventory
ansible-inventory -i ansible_hosts.yml --list

Import Errors

If you get Python import errors:

hljs language-bash

# Reinstall dependencies
pip install --upgrade -r requirements.txt

# Verify MCP installation
pip show mcp

Permission Errors

On Linux/Mac:

hljs language-bash

# Fix .env permissions
chmod 600 .env

# Make scripts executable
chmod +x *.py

📚 Additional Resources

MCP Protocol

Related Projects

📄 License

MIT License - See LICENSE file for details

🤝 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!