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.

Python 3.11 FastAPI License: MIT

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:

Lives in homeops_mcp/adapters/<name>_adapter.py
Implements a common interface (BaseAdapter)
Returns mock/demo data when the upstream service is not configured
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.