mcp-mediastack

mcp-mediastack

An MCP server that provides 50 tools for monitoring and managing a Docker-based media stack. Built with FastMCP and httpx.

Supported Services

• Sonarr - TV series management
• Radarr - Movie management
• SABnzbd - Usenet downloader
• qBittorrent - Torrent client
• Prowlarr - Indexer management
• Readarr - Book management
• Bazarr - Subtitle management
• Seerr - Media requests
• Gluetun - VPN status monitoring
• Scoutarr - Batch upgrade searches (space-saver sweep)
• Cleanuparr - Stalled-download cleanup
• Plus a space-saver sweep progress tool built on Radarr/Sonarr tags

Quick Start

Docker Run

docker run -d \
  --name mediastack-mcp \
  -p 8888:8888 \
  -e MCP_TRANSPORT=sse \
  -e NAS_HOST=192.168.1.100 \
  -e SONARR_API_KEY=your_key \
  -e RADARR_API_KEY=your_key \
  -e SABNZBD_API_KEY=your_key \
  ghcr.io/aderaaij/mcp-mediastack:latest

Docker Compose

services:
  mediastack-mcp:
    image: ghcr.io/aderaaij/mcp-mediastack:latest
    container_name: mediastack-mcp
    restart: unless-stopped
    ports:
      - 8888:8888
    environment:
      - MCP_TRANSPORT=sse
      - MCP_PORT=8888
      - NAS_HOST=192.168.1.100
      - SONARR_API_KEY=${SONARR_API_KEY}
      - RADARR_API_KEY=${RADARR_API_KEY}
      - SABNZBD_API_KEY=${SABNZBD_API_KEY}
      - PROWLARR_API_KEY=${PROWLARR_API_KEY}
      - READARR_API_KEY=${READARR_API_KEY}
      - BAZARR_API_KEY=${BAZARR_API_KEY}
      - SEERR_API_KEY=${SEERR_API_KEY}
      - QBITTORRENT_USERNAME=${QBITTORRENT_USERNAME}
      - QBITTORRENT_PASSWORD=${QBITTORRENT_PASSWORD}

Environment Variables

| Variable | Default | Description | |---|---|---| | MCP_TRANSPORT | stdio | Transport mode: stdio or sse | | MCP_PORT | 8888 | Port for SSE transport | | NAS_HOST | 192.168.1.100 | IP/hostname of your server running the media stack | | SONARR_API_KEY | | Sonarr API key (Settings > General) | | SONARR_PORT | 8989 | Sonarr port | | RADARR_API_KEY | | Radarr API key | | RADARR_PORT | 7878 | Radarr port | | SABNZBD_API_KEY | | SABnzbd API key | | SABNZBD_PORT | 8080 | SABnzbd port | | QBITTORRENT_USERNAME | admin | qBittorrent username | | QBITTORRENT_PASSWORD | adminadmin | qBittorrent password | | QBITTORRENT_PORT | 8090 | qBittorrent port | | PROWLARR_API_KEY | | Prowlarr API key | | PROWLARR_PORT | 9696 | Prowlarr port | | READARR_API_KEY | | Readarr API key | | READARR_PORT | 8787 | Readarr port | | BAZARR_API_KEY | | Bazarr API key | | BAZARR_PORT | 6767 | Bazarr port | | SEERR_API_KEY | | Seerr API key | | SEERR_PORT | 5055 | Seerr port | | GLUETUN_PORT | 8005 | Gluetun control API port | | SCOUTARR_PORT | 5839 | Scoutarr port — set explicitly to enable the Scoutarr tools | | CLEANUPARR_PORT | 11011 | Cleanuparr port — set explicitly to enable the Cleanuparr tools | | ENABLED_SERVICES | | Only load these services (comma-separated, e.g. sonarr,radarr) | | DISABLED_SERVICES | | Skip these services (comma-separated, e.g. vpn,qbittorrent) |

Selective tool loading

Tools are automatically loaded based on which API keys are set. Only set the keys for the services you use — tools for unconfigured services won't be registered.

• API key services (Sonarr, Radarr, Readarr, Prowlarr, Bazarr, SABnzbd, Seerr): enabled when their API key is non-empty
• qBittorrent and VPN: enabled by default (no API key). Use DISABLED_SERVICES=vpn,qbittorrent to disable
• Scoutarr and Cleanuparr: keyless — enabled only when SCOUTARR_PORT / CLEANUPARR_PORT is set explicitly
• Space-saver: enabled when both the Sonarr and Radarr API keys are set
• ENABLED_SERVICES: override auto-detection with an explicit whitelist (e.g. ENABLED_SERVICES=sonarr,radarr)

Tools

Monitoring (32 tools)

| Tool | Description | |---|---| | get_system_overview | Combined status of all services | | get_vpn_status | Current VPN connection info via Gluetun | | check_vpn_health | Verify VPN is working (IP leak check) | | get_sonarr_status | Sonarr system status | | get_sonarr_queue | Active download queue | | get_sonarr_calendar | Upcoming episodes | | get_sonarr_activity | Recent download history | | get_sonarr_missing | Missing episodes | | search_sonarr_series | Search existing library | | get_sonarr_library_stats | Library statistics | | get_radarr_status | Radarr system status | | get_radarr_queue | Active download queue | | get_radarr_calendar | Upcoming movies | | get_radarr_activity | Recent download history | | get_radarr_missing | Missing movies | | search_radarr_movies | Search existing library | | get_radarr_library_stats | Library statistics | | get_sabnzbd_status | SABnzbd queue and status | | get_sabnzbd_history | Download history | | get_qbittorrent_status | qBittorrent transfer info | | get_qbittorrent_torrents | List torrents with filters | | get_prowlarr_status | Indexer status and stats | | get_readarr_status | Readarr system status | | get_readarr_queue | Readarr download queue | | get_bazarr_status | Bazarr system status | | get_bazarr_wanted | Missing subtitles | | get_seerr_status | Pending requests and stats | | get_scoutarr_status | Scoutarr instance connectivity and sweep config | | get_cleanuparr_status | Cleanuparr app status and download-client health | | get_cleanuparr_events | Recent strikes, removals and re-searches | | get_space_saver_status | Space-saver sweep progress: searched/remaining counts, sizes, largest remaining items |

Actions (18 tools)

| Tool | Description | |---|---| | lookup_sonarr_series | Search for new series to add | | add_sonarr_series | Add series by TVDB ID | | sonarr_search_missing | Trigger search for missing episodes | | sonarr_remove_from_queue | Remove stuck queue items | | lookup_radarr_movies | Search for new movies to add | | add_radarr_movie | Add movie by TMDB ID | | radarr_search_missing | Trigger search for missing movies | | radarr_remove_from_queue | Remove stuck queue items | | send_arr_command | Send a command to Sonarr/Radarr/Readarr (e.g. RefreshSeries, CheckHealth) | | run_scoutarr_sweep | Trigger a Scoutarr sweep run (all instances, blocks ~4-5 min) | | sabnzbd_pause_resume | Pause or resume SABnzbd | | sabnzbd_delete_job | Delete a download job | | sabnzbd_retry_failed | Retry a failed download | | qbittorrent_pause_torrents | Pause torrents | | qbittorrent_resume_torrents | Resume torrents | | qbittorrent_delete_torrents | Delete torrents | | seerr_approve_request | Approve a media request | | seerr_decline_request | Decline a media request |

Claude Desktop Integration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

Direct (stdio, same machine)

{
  "mcpServers": {
    "mediastack": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "NAS_HOST=192.168.1.100",
        "-e", "SONARR_API_KEY=your_key",
        "ghcr.io/aderaaij/mcp-mediastack:latest"
      ]
    }
  }
}

Remote (SSE via mcp-remote)

If the server is running on a remote host with SSE transport:

{
  "mcpServers": {
    "mediastack": {
      "command": "npx",
      "args": ["mcp-remote", "http://your-server:8888/sse"]
    }
  }
}

Known Quirks

• httpx params: Never pass params={} (empty dict) to httpx — it strips query parameters from the URL. Only pass params when non-empty.
• Seerr titles: Seerr requests don't include titles directly. The server resolves them via TMDB lookups using the media's TMDB ID.
• qBittorrent auth: Uses session-based cookie auth, not API keys. The server handles login automatically.

Development

# Install dependencies
uv sync

# Run locally (stdio mode)
python -m mcp_mediastack

# Run locally (SSE mode)
MCP_TRANSPORT=sse python -m mcp_mediastack

License

MIT