# Homelab Mcp

> Model Context Protocol (MCP) servers for managing homelab infrastructure through Claude Desktop. Monitor Docker/Podman containers, Ollama AI models, Pi-hole DNS, Unifi networks, and Ansible inventory. Includes security checks, templates, and automated pre-push validation. Production-ready for homelabs.

- **Type:** MCP server
- **Install:** `agentstack add mcp-bjeans-homelab-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [bjeans](https://agentstack.voostack.com/s/bjeans)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bjeans](https://github.com/bjeans)
- **Source:** https://github.com/bjeans/homelab-mcp

## Install

```sh
agentstack add mcp-bjeans-homelab-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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
- **[MIGRATION_V3.md](MIGRATION_V3.md)** - Migration guide for v2.0 unified server
- **[PROJECT_INSTRUCTIONS.md](PROJECT_INSTRUCTIONS.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 PROJECT_INSTRUCTIONS.md to Claude
**🔄 Migrating from v1.x?** See [MIGRATION_V3.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 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**.

```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**.

```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](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](#-docker-deployment-alternative) for full setup instructions.

**Quick Start:**
```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](#-installation) for full setup instructions.

**Quick Start:**
```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](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.

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

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

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

```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

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

### 2. Install security checks (recommended)

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

### 3. Set up configuration files

**Environment variables:**

```bash
# Windows
copy .env.example .env

# Linux/Mac
cp .env.example .env
```

Edit `.env` with your actual values:

```bash
# Windows
notepad .env

# Linux/Mac
nano .env
```

**Ansible inventory (if using):**

```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:**

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

```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

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

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

```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](MIGRATION_V3.md) for details. The deprecated mcp-registry-inspector has been removed from this example. Ansible MCP server integration is tracked in [#39](https://github.com/bjeans/homelab-mcp/issues/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](https://hub.docker.com/r/bjeans/homelab-mcp)

### Quick Start with Docker Hub (Easiest)

**Pre-built images are automatically published to Docker Hub with multi-platform support (amd64/arm64):**

```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-` - 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:**

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

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-bjeans-homelab-mcp
- Seller: https://agentstack.voostack.com/s/bjeans
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.