TheBoringMCP

Ein einziger MCP-Server (Model Context Protocol) mit vollem Zugriff auf dein HomeLab: Home Assistant, Portainer, Sonarr, Radarr, SABnzbd und Jellyfin – nutzbar direkt aus Claude heraus.

Gebaut, weil der Alltag im HomeLab zu langweilig sein sollte, um sich noch selbst darum zu kümmern. Daher der Name.

Features

Jeder Dienst ist einzeln optional – fehlt die Konfiguration für einen Dienst, werden dessen Tools beim Start einfach nicht registriert (siehe Konsolen-Log beim Start).

Referenz-Projekt für den Home-Assistant-Teil war homeassistant-ai/ha-mcp; TheBoringMCP bündelt zusätzlich Portainer und den ARR-Stack in einem Server, statt mehrere MCP-Server parallel betreiben zu müssen.

Related MCP server: homelab-ai

Betriebsarten

TheBoringMCP unterstützt zwei Transportmodi:

1. stdio (Standard) – für die lokale Nutzung z.B. mit Claude Desktop oder Claude Code, wo der Prozess direkt vom Client gestartet wird.

2. HTTP (Streamable) – für den Dauerbetrieb als Container/Add-on, das Claude per URL erreicht (TRANSPORT=http).

1) Als Home Assistant Add-on

1. In Home Assistant: Einstellungen -> Add-ons -> Add-on-Store -> ⋮ -> Repositories -> URL dieses Repos eintragen.

2. "TheBoringMCP" installieren, Optionen ausfüllen (siehe DOCS.md), starten.

3. Claude als Remote-MCP-Server auf http://<ha-ip>:17820/ mit Authorization: Bearer <mcp_http_token> verbinden.

2) Als eigenständiger Docker-Container

git clone https://github.com/theboringalex/TheBoringMCP.git
cd TheBoringMCP
cp docker-compose.yml docker-compose.local.yml   # optional, Werte anpassen
docker compose up -d --build

Der Server läuft danach unter http://<host>:17820/.

3) Lokal per stdio (Claude Desktop / Claude Code)

git clone https://github.com/theboringalex/TheBoringMCP.git
cd TheBoringMCP
npm install
npm run build

In der Claude-Desktop-Konfiguration (claude_desktop_config.json):

{
  "mcpServers": {
    "theboringmcp": {
      "command": "node",
      "args": ["/pfad/zu/TheBoringMCP/dist/index.js"],
      "env": {
        "HA_URL": "http://192.168.1.11:8123",
        "HA_TOKEN": "...",
        "PORTAINER_URL": "https://192.168.1.11:9444",
        "PORTAINER_API_KEY": "...",
        "SONARR_URL": "http://192.168.1.5:8989",
        "SONARR_API_KEY": "...",
        "RADARR_URL": "http://192.168.1.5:7878",
        "RADARR_API_KEY": "...",
        "SABNZBD_URL": "http://192.168.1.5:6554",
        "SABNZBD_API_KEY": "...",
        "JELLYFIN_URL": "http://192.168.1.5:8096",
        "JELLYFIN_API_KEY": "..."
      }
    }
  }
}

Konfiguration (Umgebungsvariablen)

Alle Variablen sind optional – nur die für die gewünschten Dienste gesetzten Variablen werden aktiviert.

Sicherheit

TheBoringMCP gibt vollen, ungefilterten Zugriff – inklusive Löschen von Containern, Automationen, Filmen/Serien und mehr. Im HTTP-Modus immer MCP_HTTP_TOKEN setzen und den Port nicht ohne Reverse Proxy/TLS ins Internet exponieren. Für reine Auswertung/Dashboards READ_ONLY=true verwenden.

Entwicklung

npm install
npm run dev     # tsx watch – Neustart bei Codeänderungen
npm run build   # -> dist/
npm run lint    # tsc --noEmit

Projektstruktur:

src/
  clients/     # Ein API-Client pro Dienst (nur HTTP, keine MCP-Logik)
  tools/       # MCP-Tool-Definitionen pro Dienst (zod-Schemas + Handler)
  config.ts    # Lädt Konfiguration aus ENV
  index.ts     # Server-Bootstrap (stdio/HTTP)
  http-server.ts

Versionierung

Dieses Projekt folgt Semantic Versioning und dokumentiert alle Änderungen in CHANGELOG.md nach dem Keep a Changelog-Format.

Lizenz

MIT – siehe LICENSE.