Homelab MCP Servers

<p align="center"> <img src="assets/Homelab-mcp-logo-transparent.png" alt="Homelab MCP Logo" width="400"> </p>

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:

1. Copy the example template:

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

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

3. 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 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:

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

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