media-mcp

media-mcp

Serveur MCP local (transport stdio) pour piloter un stack média self-hosted.Première itération : Sonarr + Radarr.

Prérequis

• Python 3.11+
• uv installé

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 et attend des messages MCP sur stdin/stdout.

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"
      }
    }
  }
}

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

Variables d'environnement

Tools disponibles

Sonarr

Radarr

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 faitcô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 noteshowing N of up to {limit} (searched the {window} most recent events).

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
  server.py          # instancie FastMCP et enregistre tous les tools
  __main__.py        # entrypoint: python -m media_mcp
  clients/
    base.py          # ArrClient: httpx async, gestion des erreurs
    sonarr.py        # SonarrClient(ArrClient)
    radarr.py        # RadarrClient(ArrClient)
  tools/
    sonarr_tools.py  # @mcp.tool pour Sonarr
    radarr_tools.py  # @mcp.tool pour Radarr

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