HomeOps 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

Phase	Scope	Status
Phase 0	Skeleton -- project structure, CI, Docker build, health endpoint	Done
Phase 1	Docker + Emby adapters, API-key auth middleware, full CI pipeline	Planned
Phase 2	Servarr (Sonarr/Radarr/Prowlarr), WordPress, Synology, UniFi, CrowdSec adapters	Planned
Phase 3	UI dashboard, audit logs, secrets management (Vault/SOPS), production hardening	Planned

---

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.

Variable	Required	Default	Description
MCP_ADMIN_KEY	Yes	changeme-to-a-strong-random-key	API key for admin endpoints
LOG_LEVEL	No	INFO	Logging level (DEBUG, INFO, WARNING, ERROR)
EMBY_URL	No	(mock data)	Emby server URL, e.g. http://192.168.1.100:8096
EMBY_API_KEY	No	(mock data)	Emby API key for authentication
DOCKER_SOCKET	No	unix:///var/run/docker.sock	Path to Docker socket

---

API Endpoints

Method	Path	Auth	Description
GET	/health	No	Health check -- returns {"status": "ok"}
GET	/v1/docker/containers	API Key	List Docker containers
GET	/v1/docker/containers/{id}/stats	API Key	Container resource stats
GET	/v1/emby/sessions	API Key	List active Emby sessions
GET	/v1/emby/search?q=term	API Key	Search Emby library
POST	/v1/actions/execute	API Key	Log action (non-destructive)

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.