Which integrations are available for this server?

Allows listing Docker containers and retrieving real-time resource statistics for containerized home infrastructure. Provides tools to search the media library and monitor active streaming sessions on an Emby server. Enables automated management of movie libraries and download queues (planned integration). Enables automated management of TV show libraries and download queues (planned integration). Provides management and monitoring capabilities for Synology NAS infrastructure (planned integration). Integrates with HashiCorp Vault for secure secrets management and protection of infrastructure credentials (planned integration). Allows for programmatic management and automation of WordPress site instances (planned integration).

How do I use HomeOps MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@HomeOps MCP Server show me all running Docker containers and active Emby sessions" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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 .