HomeOps MCP Server

Note: This project was developed with and is supported exclusively by AI. There is no human support — issues and PRs are triaged and responded to by AI agents. If AI-assisted software isn't for you, no hard feelings — but you might want to reconsider, since so is most of the software you already use.

A Model Context Protocol (MCP) server for home infrastructure management. Provides a unified API for Docker, Emby, and future Servarr/UniFi/CrowdSec integrations. Built with FastAPI and Python 3.11 for homelab automation with Claude.

Roadmap

Quick Start

Option A -- Docker Compose (recommended)

cp .env.example .env
# Edit .env with your real values
docker compose up -d

The server will be available at http://localhost:8000.

Option B -- Run locally

# Requires Python 3.11+ and Poetry
poetry install
bash scripts/run_local.sh

Configuration

All configuration is via environment variables. Copy .env.example to .env and edit as needed.

API Endpoints

All authenticated endpoints require the X-API-Key header set to the value of MCP_ADMIN_KEY.

Security

• Never commit real API keys or secrets. The .env file is git-ignored.

• Only placeholder values appear in .env.example.

• The Docker socket is mounted read-only in docker-compose.yml.

• The container runs as a non-root user (appuser).

• All adapter API keys are loaded from environment variables at startup and are never logged.

Architecture

HomeOps MCP uses an adapter pattern to integrate with external services:

Client Request
      |
      v
  FastAPI Router
      |
      v
  Auth Middleware  (validates X-API-Key)
      |
      v
  Adapter Layer
      |
      +---> DockerAdapter    --> Docker Engine API (socket)
      +---> EmbyAdapter      --> Emby REST API
      +---> ServarrAdapter   --> Sonarr / Radarr / Prowlarr APIs  (Phase 2)
      +---> UniFiAdapter     --> UniFi Controller API              (Phase 2)
      +---> CrowdSecAdapter  --> CrowdSec LAPI                    (Phase 2)

Each adapter:

1. Lives in homeops_mcp/adapters/<name>_adapter.py

2. Implements a common interface (BaseAdapter)

3. Returns mock/demo data when the upstream service is not configured

4. Has its own unit tests in tests/

Development

# Install all dependencies (including dev)
poetry install

# Run linter
poetry run ruff check .

# Run tests
poetry run pytest -v

# Build Docker image
docker build -t homeops-mcp .

Contributing

Every issue in this repo is AI-Ready — structured with full context, file paths, implementation guides, and a ready-to-use AI prompt.

Browse Issues →

License

MIT -- see LICENSE.