Homelab Mcp

Homelab MCP Servers

[](https://github.com/bjeans/homelab-mcp/releases) [](https://github.com/bjeans/homelab-mcp/actions/workflows/security-check.yml) [](https://github.com/bjeans/homelab-mcp/actions/workflows/docker-publish.yml) [](https://hub.docker.com/r/bjeans/homelab-mcp) [](https://hub.docker.com/r/bjeans/homelab-mcp) [](https://github.com/bjeans/homelab-mcp/blob/main/LICENSE)

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](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](SECURITY.md) for comprehensive security guidance.

� Documentation Overview

This project includes several documentation files for different audiences:

• [README.md](README.md) (this file) - Installation, setup, and usage guide
• [MIGRATIONV3.md](MIGRATIONV3.md) - Migration guide for v2.0 unified server
• [PROJECTINSTRUCTIONS.md](PROJECTINSTRUCTIONS.example.md) - Copy into Claude project instructions for AI context
• [CLAUDE.md](CLAUDE.md) - Developer guide for AI assistants and contributors
• [SECURITY.md](SECURITY.md) - Security policies and best practices
• [CONTRIBUTING.md](CONTRIBUTING.md) - How to contribute to this project
• [CHANGELOG.md](CHANGELOG.md) - Version history and changes

👥 For End Users: Follow this README + copy PROJECTINSTRUCTIONS.md to Claude 🔄 Migrating from v1.x? See [MIGRATIONV3.md](MIGRATION_V3.md) for unified server migration 🤖 For AI Assistants: Read [CLAUDE.md](CLAUDE.md) for complete development context 🔧 For Contributors: Start with CONTRIBUTING.md and [CLAUDE.md](CLAUDE.md)

�📖 Important: Configure Claude Project Instructions

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

1. Copy the example template:

```bash # Windows copy PROJECTINSTRUCTIONS.example.md PROJECTINSTRUCTIONS.md

# Linux/Mac cp PROJECTINSTRUCTIONS.example.md PROJECTINSTRUCTIONS.md ```

1. 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

1. 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.

{
  "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 [MIGRATIONV3.md](MIGRATIONV3.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](#-docker-deployment-alternative) 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](#-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 [MIGRATIONV3.md](MIGRATIONV3.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.

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

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

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

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

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 [MIGRATIONV3.md](MIGRATIONV3.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):

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

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

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [bjeans](https://github.com/bjeans)
- **Source:** [bjeans/homelab-mcp](https://github.com/bjeans/homelab-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.