media-mcp

Serveur MCP pour piloter un stack média self-hosted : Sonarr + Radarr, qBittorrent via qui (autobrr), Prowlarr (indexeurs) et Jellyfin (collections curatives / BoxSets).

Deux transports : stdio (défaut, dev local / Claude Desktop) et HTTP (service Docker sur le homelab). Voir Déploiement.

Prérequis

• Python 3.11+

• uv installé

Related MCP server: MCP *arr Server

Installation

# Cloner / se placer dans le répertoire du projet
cd media-mcp

# Installer les dépendances
uv sync

# Copier et remplir les variables d'environnement
cp .env.example .env
# Éditer .env avec vos URLs et clés API

Lancement en développement

uv run python -m media_mcp

Le serveur démarre en mode stdio (défaut) et attend des messages MCP sur stdin/stdout.

Pour le lancer en HTTP localement :

MCP_TRANSPORT=http PORT=8080 uv run python -m media_mcp
# endpoint MCP : http://127.0.0.1:8080/mcp

Configuration Claude Desktop

Ajouter dans ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows) :

{
  "mcpServers": {
    "media-mcp": {
      "command": "uv",
      "args": ["--directory", "/chemin/absolu/media-mcp", "run", "python", "-m", "media_mcp"],
      "env": {
        "SONARR_URL": "http://localhost:8989",
        "SONARR_API_KEY": "xxx",
        "RADARR_URL": "http://localhost:7878",
        "RADARR_API_KEY": "xxx",
        "QUI_URL": "https://qui.example.com",
        "QUI_API_KEY": "xxx",
        "QUI_INSTANCE": "",
        "PROWLARR_URL": "http://localhost:9696",
        "PROWLARR_API_KEY": "xxx"
      }
    }
  }
}

Remplacer /chemin/absolu/media-mcp par le chemin réel du projet.

Variables d'environnement

Tools disponibles

Sonarr

Radarr

qBittorrent (via qui)

Accès uniquement via qui (le gestionnaire web multi-instance d'autobrr), jamais via l'API qBittorrent directe. Auth par header X-API-Key. Les tools ciblent l'instance résolue depuis QUI_INSTANCE (id ou nom) ; si vide et qu'une seule instance existe, elle est choisie automatiquement ; si plusieurs, une erreur liste les instances disponibles.

Les tools prenant un hash acceptent le hash complet (40 car., copiable depuis qbit_list_torrents) ou un préfixe unique ; un préfixe ambigu liste les candidats sans agir.

Le hash qBittorrent est la clé de liaison : c'est la valeur renvoyée par le downloadId de l'historique Sonarr/Radarr. La comparaison est insensible à la casse (qBit renvoie le hash en minuscules, les *arr souvent en majuscules).

Prowlarr (indexeurs)

Gestionnaire d'indexeurs Servarr — API en /api/v1 (et non v3), auth X-Api-Key. Orienté diagnostic des indexeurs.

prowlarr_indexer_status ne porte pas de message textuel de raison (l'API /indexerstatus n'expose que indexerId + horodatages) : il croise la liste des indexeurs pour le nom et affiche la date de reprise (disabledTill). Pour le « pourquoi » global, voir prowlarr_health.

Recherche & grab (contenu hors-*arr : ebooks, manga, logiciels…)

prowlarr_search interroge tous les indexeurs et renvoie, par release, la référence de grab (guid + indexerId) à passer à prowlarr_grab. Les résultats sont triés par seeders décroissant (le limit de Prowlarr n'étant pas un vrai plafond, la coupe est faite côté client).

prowlarr_grab envoie la release au download client configuré dans Prowlarr (dry-run par défaut ; confirm=True pour exécuter). Aucune catégorie n'est passée par le MCP : le classement final dans qBittorrent (ebook / logiciel / autre) est décidé par les Mapped Categories du download client, à configurer dans l'UI Prowlarr (Settings → Download Clients). S'il n'y a aucun download client, le grab renvoie un message clair (à ajouter d'abord dans l'UI). La recherche/le grab avec catégorie explicite restent gérés côté Prowlarr, pas ici.

Jellyfin (collections curatives / BoxSets)

Serveur média Jellyfin — endpoints à la racine du serveur (pas de préfixe /api/vN), auth par header Authorization: MediaBrowser Token="<clé>". Objectif : créer et gérer des collections curatives (BoxSets) avec description, pilotables en langage naturel.

Client autonome (ne dérive PAS d'ArrClient, comme QuiClient) : Jellyfin n'est pas une API *arr. Le userId requis par les endpoints d'items est résolu une fois (premier compte Policy.IsAdministrator via GET /Users) puis mis en cache pour la durée du process.

Résolution des films (movies) et références (collection_ref / item_ref)

Le paramètre movies accepte une liste mixte : tmdbId numériques, ids Jellyfin (ou préfixe unique de 8 car.), ou titres approximatifs (casse/accents/articles/ponctuation normalisés — « Le Solitaire » ≈ « solitaire »). La résolution est une cascade qui s'arrête au premier niveau donnant un match unique :

1. tmdbId exact (via ProviderIds.Tmdb)

2. id Jellyfin, ou préfixe unique

3. Name Jellyfin normalisé

4. OriginalTitle Jellyfin normalisé

5. repli Radarr — Radarr connaît les titres localisés/alternatifs (title, originalTitle, alternateTitles) que Jellyfin n'indexe parfois que sous un titre anglais. Le titre demandé y est matché, son tmdbId récupéré, puis rebranché sur Jellyfin par tmdbId. Utilise le client Radarr interne (jamais un appel vers nos propres tools MCP) ; si Radarr n'est pas configuré ou est injoignable, le niveau 5 est simplement sauté (not_found propre, aucune exception).

La règle est identique à chaque niveau : un seul candidat → matched ; plusieurs → ambiguous (candidats remontés, jamais un choix arbitraire) ; aucun → niveau suivant.

Chaque movies déclenche au plus un fetch bibliothèque Jellyfin + au plus un fetch Radarr (ce dernier uniquement si une référence atteint le niveau 5, en lazy). Les dry-runs (confirm=False) affichent exactement les films matched / ambiguous / not found avant toute écriture, avec une colonne indiquant le moyen de résolution (tmdb / id / title / original-title / via-radarr) ; un match via-radarr (le plus faillible) affiche en clair le titre Radarr ET le titre Jellyfin retenus. Sur confirm=True, une création/modification refuse de procéder si des références restent non résolues (pas de collection partielle en silence). ProviderIds.Tmdb est le pont fiable avec le tmdbId Radarr (jamais de match sur le titre en interne quand un tmdbId existe).

Pièges Jellyfin gérés

• POST /Items/{id} = GET-modify-POST du BaseItemDto complet (pas de PATCH). Un DTO partiel renvoie 400 et peut corrompre l'item jusqu'au prochain rescan (champs collection null passés à .ToList()). Avant tout envoi, les champs tableau (Tags, Genres, Studios, People, LockedFields, GenreItems, TagItems…) sont normalisés en [] (jamais null) et ProviderIds en {} (map, pas liste). Un test respx vérifie explicitement qu'aucun null ne part dans un champ tableau.

• Verrouillage : après écriture d'un Overview, "Overview" est ajouté à LockedFields (verrou au niveau champ) pour qu'un refresh de métadonnées n'écrase pas la description. Comportement par défaut, désactivable via lock=False.

• Bibliothèque « Collections » absente : POST /Collections peut renvoyer une 500 (Sequence contains no elements) ; c'est traduit en message actionnable (créer une première collection depuis l'UI web) plutôt qu'une erreur brute.

Cadrage : l'upload d'affiche (jellyfin_set_collection_image) n'est pas dans cette itération — la place est prévue dans l'architecture (POST /Items/{id}/Images/Primary, corps base64 + Content-Type réel), à ajouter ensuite.

Tools coordonnés — purge « partout »

Suppriment, en un geste avec aperçu et confirm, les fichiers bibliothèque (Sonarr/Radarr) ET le(s) torrent(s) correspondants côté qBittorrent-via-qui, cross-seeds inclus.

Flux :

1. Lister les fichiers concernés côté *arr (saison / film) → nombre + taille.

2. Extraire les downloadId depuis l'historique *arr (/history/series, /history/movie) → ensemble des hash d'origine (dédupliqués ; un season pack partage un seul downloadId).

3. Côté qui, pour chaque origine : résoudre le torrent, puis local-matches?strict=true → cross-seeds (siblings).

4. Ensemble à supprimer = origines présentes ∪ siblings, dédupliqué par hash. include_loose_matches=False exclut les siblings match_type ∈ {name, release} (garde les matches content_path) et indique combien ont été exclus.

5. Dry-run (confirm=False) : aperçu exhaustif des deux côtés, rien supprimé. confirm=True : suppression des fichiers *arr puis un seul bulk-action delete (avec deleteFiles selon delete_torrent_files) sur tous les hash ; rapport combiné.

Cas limites gérés (sans planter) : aucun downloadId (historique purgé → suppression biblio seule, torrents à gérer à la main) ; origine absente de qBit (ignorée, signalée) ; saison/film sans fichier (torrents traités quand même) ; cross-seed indispo (repli sur les origines seules).

Honnêteté sur l'espace disque : les tailles bibliothèque et torrents ne sont jamais additionnées — hardlinkées, ce sont généralement les mêmes octets. L'aperçu les montre séparément et rappelle que, comme on supprime les deux côtés (+ cross-seeds), l'espace de ce contenu sera cette fois réellement libéré (≈ la plus grande des deux tailles, pas la somme).

Pattern dry-run / confirm

Toutes les actions à effet de bord (add_*, delete_*, search_*) acceptent un paramètre confirm:

• confirm=False (défaut) → aperçu sans exécution (dry-run)

• confirm=True → exécution réelle

Note hardlink : les tools de suppression de fichiers (sonarr_delete_season, sonarr_delete_episode_file, radarr_delete_movie_file) retirent les fichiers côté Sonarr/Radarr uniquement. Si les fichiers sont en hardlink avec un client torrent, l'espace disque n'est pas libéré tant que le torrent n'est pas aussi supprimé côté client. L'aperçu dry-run le rappelle.

Filtre event_type de *_history

L'API attend un entier pour son query param eventType, donc le filtrage est fait côté client sur le champ texte eventType de chaque événement. event_type accepte :

La chaîne canonique exacte est aussi acceptée (ex. event_type="downloadFolderImported"). Une valeur inconnue renvoie un message listant les valeurs valides, sans appel API. Comme le filtrage est côté client sur une fenêtre élargie (une requête, pageSize = max(limit*5, 100)), un résultat filtré partiel ajoute une note showing N of up to {limit} (searched the {window} most recent events).

Diagnostic & regroupement de *_queue

sonarr_queue / radarr_queue surfacent, pour chaque item, pourquoi il est bloqué : trackedDownloadStatus / trackedDownloadState (ex. warning / importBlocked), le texte des statusMessages et l'errorMessage éventuel. Les messages par item sont bornés ((+N more)) pour rester lisibles ; un champ absent/null est géré sans erreur.

Les items partageant le même downloadId (un season pack = un torrent, N lignes) sont regroupés en une entrée [×N] affichant le downloadId (le pont vers qBittorrent) et la ligne ids: … (les queue IDs individuels du groupe, tronquée si trop longue). Les items sans downloadId restent individuels et conservent taille/ETA.

*_delete_queue_item accepte exactement un de queue_id (un item) ou download_id (tous les items du download, retirés en un seul DELETE /queue/bulk) ; en dry-run il liste le nombre d'items, leur(s) titre(s) et les IDs ciblés avant toute suppression.

Déploiement

⚠️ Sécurité — l'image GHCR est PUBLIQUE

• Ne jamais mettre de secret dans l'image, le Dockerfile, un workflow ou un fichier suivi par git. Toutes les clés et URLs arrivent au runtime (env_file / environment / docker run -e). Le Dockerfile ne déclare que MCP_TRANSPORT, HOST et PORT.

• .dockerignore exclut .env*, .git, tests/, .venv… : rien de sensible n'entre dans le build context.

• .gitignore exclut .env, ses variantes et le vrai docker-compose.yml. Seuls .env.example et docker-compose.example.yml (placeholders) sont committés.

• Les URLs configurées doivent être les URLs INTERNES du homelab (http://sonarr:8989, http://qui:7476…), jamais les URLs Cloudflare/publiques : elles ne doivent ni fuiter ni faire transiter le trafic par l'extérieur.

• Le serveur MCP n'a aucune authentification : ne pas publier son port hors du homelab.

Transports

Le défaut reste stdio : la config Claude Desktop existante fonctionne sans changement. Une valeur inconnue fait échouer le démarrage avec la liste des valeurs acceptées.

Build & run Docker

docker build -t media-mcp:local .

# L'image démarre en HTTP sur 8080 (MCP_TRANSPORT=http est le défaut DANS l'image)
docker run --rm -p 127.0.0.1:8080:8080 --env-file .env media-mcp:local

L'image est multi-stage (deps résolues par uv, puis seul le venv est copié), tourne en non-root (uid 10001) et n'embarque ni les tests, ni .env, ni .git.

docker-compose (homelab)

cp docker-compose.example.yml docker-compose.yml   # le vrai compose est gitignoré
cp .env.example .env                                # puis remplir avec les URLs INTERNES
docker compose up -d

Réseau : media-mcp doit être sur le même réseau Docker que les services *arr / qui / Prowlarr / Jellyfin pour les joindre par nom de conteneur. Le compose d'exemple s'attache à un réseau external — le remplacer par le réseau réel (docker network ls). Si le client MCP (Hermes) tourne dans ce même réseau, il joint http://media-mcp:8080/mcp directement : inutile de publier le port.

CI/CD (GitHub Actions)

L'auth GHCR passe par le GITHUB_TOKEN intégré (permissions: packages: write) : aucun PAT ni secret perso à stocker. Les workflows ne contiennent aucun secret applicatif — ils buildent l'image, ils ne la font pas tourner.

Rendre le package public (une seule fois, après le premier push) : GitHub → onglet Packages → media-mcp → Package settings → Change visibility → Public. Les packages GHCR sont privés par défaut.

Développement

# Lint & format
uv run ruff check src tests
uv run ruff format src tests

# Tests
uv run pytest

Architecture

src/media_mcp/
  config.py          # pydantic-settings — lit les variables d'env
  models.py          # modèles pydantic pour les réponses simplifiées
  coordinated.py     # service d'orchestration purge (arr + qui), logique lourde
  jellyfin_resolve.py   # résolution en cascade (tmdbId/id/Name/OriginalTitle + repli Radarr injecté)
  server.py          # instancie FastMCP (host/port) et enregistre tous les tools
  __main__.py        # entrypoint: python -m media_mcp — résout MCP_TRANSPORT
  clients/
    base.py          # ArrClient: httpx async, gestion des erreurs
    sonarr.py        # SonarrClient(ArrClient)
    radarr.py        # RadarrClient(ArrClient)
    prowlarr.py      # ProwlarrClient(ArrClient) — /api/v1
    qui.py           # QuiClient: httpx async, header X-API-Key (NE dérive PAS d'ArrClient)
    jellyfin.py      # JellyfinClient: root path, MediaBrowser Token (NE dérive PAS d'ArrClient)
  tools/
    sonarr_tools.py  # @mcp.tool pour Sonarr
    radarr_tools.py  # @mcp.tool pour Radarr
    qbit_tools.py    # @mcp.tool pour qBittorrent via qui
    prowlarr_tools.py     # @mcp.tool pour Prowlarr (indexeurs)
    coordinated_tools.py  # @mcp.tool purge saison/film "partout" (arr + qui)
    jellyfin_tools.py     # @mcp.tool pour Jellyfin (collections curatives / BoxSets)

Déploiement :

Dockerfile                  # image multi-stage (uv -> venv), non-root, http:8080
.dockerignore               # garde secrets/tests/.git hors du build context
docker-compose.example.yml  # modèle homelab (le vrai docker-compose.yml est gitignoré)
.github/workflows/
  ci.yml                    # PR : lint + tests + build sans push
  release.yml               # main : build + push GHCR (latest + SHA)

Ajouter un nouveau service (ex. Jellyseerr) : créer clients/jellyseerr.py et tools/jellyseerr_tools.py, puis enregistrer dans server.py.