sonarr-mcp

Sonarr MCP Server

A feature-rich but simple-to-use MCP (Model Context Protocol) server for managing your Sonarr (TV show) instance.

Features

• Complete Series Management: Search, add, edit, and delete TV series
• Episode Control: View episodes, search for missing episodes, manage seasons
• Download Queue: Monitor downloads, remove stuck items, manage blocklists
• Calendar & Scheduling: See upcoming episodes, track releases
• System Health: Monitor instance health, check for issues
• Configuration Management: Quality profiles, language profiles, root folders, tags

Installation

cd mcp-sonarr
npm install
npm run build

Configuration

Set these environment variables:

export SONARR_URL="http://localhost:8989"        # Your Sonarr URL
export SONARR_API_KEY="your-api-key-here"        # Your API key (Settings > General)

Or on Windows:

$env:SONARR_URL="http://localhost:8989"
$env:SONARR_API_KEY="your-api-key-here"

MCP Client Configuration

Add to your MCP client config:

{
  "mcpServers": {
    "sonarr": {
      "command": "node",
      "args": ["<YOUR_OPENCODE_DIR>/mcp-sonarr/dist/server.js"],
      "env": {
        "SONARR_URL": "http://localhost:8989",
        "SONARR_API_KEY": "your-api-key-here"
      }
    }
  }
}

For development with hot reload:

{
  "mcpServers": {
    "sonarr": {
      "command": "npx",
      "args": [
        "tsx",
        "<YOUR_OPENCODE_DIR>/mcp-sonarr/src/server.ts"
      ],
      "env": {
        "SONARR_URL": "http://localhost:8989",
        "SONARR_API_KEY": "your-api-key-here"
      }
    }
  }
}

Available Tools

Series Management

sonarr_search_series

Search for TV series by title on TVDB/TMDB. Returns potential matches with metadata.

Input:

• term (string, required): Search term (e.g., "Breaking Bad", "The Office")

Output: List of matching series with tvdbId, title, year, overview, seasons count, etc.

Note: Use the tvdbId to add a series with sonarr_add_series

---

sonarr_get_all_series

Get all series in your Sonarr library.

Output: Complete list of all series with metadata, statistics (episode counts, disk usage), monitoring status.

---

sonarr_get_series

Get detailed information about a specific series by its Sonarr ID.

Input:

• id (number, required): Sonarr series ID

Output: Full series details including all seasons, episode statistics, images, ratings, and next actions.

---

sonarr_get_series_by_tvdb

Get series information by TVDB ID.

Input:

• tvdbId (number, required): TVDB ID (e.g., 81189 for Breaking Bad)

---

sonarr_add_series

Add a new TV series to your library.

Input:

• tvdbId (number, required): TVDB ID from search results
• monitored (boolean, optional): Whether to monitor the series (default: true)
• rootFolderPath (string, optional): Where to store the series (uses default if not specified)
• qualityProfileId (number, optional): Quality profile to use (uses default if not specified)
• languageProfileId (number, optional): Language profile to use
• seasonFolder (boolean, optional): Create season folders (default: true)
• tags (number[], optional): Array of tag IDs
• seasons (object[], optional): Specify which seasons to monitor

---

sonarr_delete_series

Delete a series from Sonarr. Optionally delete files from disk.

⚠️ WARNING: Deleting files is permanent and cannot be undone!

Input:

• id (number, required): Series ID to delete
• deleteFiles (boolean, optional): Also delete files from disk (default: false)
• addImportListExclusion (boolean, optional): Prevent re-import (default: false)

---

sonarr_edit_series

Edit an existing series (monitoring, quality profile, tags, etc.).

Input:

• series (object, required): Complete series object with modifications. Must include id field.

Tip: Get the full series object first with sonarr_get_series, modify it, and pass it here.

Episode Management

sonarr_get_episodes

Get all episodes for a specific series.

Input:

• seriesId (number, required): Sonarr series ID
• seasonNumber (number, optional): Filter by specific season

Output: Episodes list with air dates, file status, monitoring status, and statistics.

---

sonarr_get_episode

Get detailed information about a specific episode.

Input:

• id (number, required): Episode ID

---

sonarr_search_episodes

Search for specific episodes to download. This sends episodes to your download client.

Input:

• episodeIds (number[], required): Array of episode IDs to search for

---

sonarr_search_season

Search for all episodes in a specific season.

Input:

• seriesId (number, required): Sonarr series ID
• seasonNumber (number, required): Season number to search

---

sonarr_search_series_command

Search for all monitored episodes across a series (the "Search All" button).

Input:

• seriesId (number, required): Sonarr series ID

Queue & Downloads

sonarr_get_queue

Get current download queue. Shows active downloads, progress, status, and errors.

Input:

• page (number, optional): Page number (default: 1)
• pageSize (number, optional): Items per page (default: 20)
• sortKey (string, optional): Sort field (default: "timeleft")
• sortDirection (string, optional): "ascending" or "descending" (default: "ascending")
• includeUnknownSeriesItems (boolean, optional): Include unknown items (default: false)

Output: Queue items with progress percentage, status, time remaining, and errors.

---

sonarr_remove_from_queue

Remove an item from the download queue.

Input:

• id (number, required): Queue item ID
• blocklist (boolean, optional): Blocklist release to prevent re-download (default: false)
• skipRedownload (boolean, optional): Skip retrying the episode (default: false)
• changeCategory (boolean, optional): Change category in download client (default: false)

Calendar & Missing Episodes

sonarr_get_wanted

Get wanted/missing episodes that are monitored but don't have files.

Input:

• page (number, optional): Page number (default: 1)
• pageSize (number, optional): Items per page (default: 20)
• sortKey (string, optional): Sort field (default: "airDateUtc")
• sortDirection (string, optional): "ascending" or "descending" (default: "descending")

Output: Missing episodes with series info, ready for searching.

---

sonarr_get_calendar

Get episodes airing in a date range. Great for seeing what's coming up.

Input:

• start (string, optional): Start date (YYYY-MM-DD, defaults to today)
• end (string, optional): End date (YYYY-MM-DD, defaults to 7 days from start)
• unmonitored (boolean, optional): Include unmonitored episodes (default: false)
• includeSeries (boolean, optional): Include series data (default: false)
• includeEpisodeFile (boolean, optional): Include episode file data (default: false)

Output: Episodes grouped by date with air times and availability status.

System & Configuration

sonarr_get_health

Get system health status. Shows warnings or errors with your Sonarr instance.

Output: Health status with error/warning/notice counts and detailed messages.

---

sonarr_get_system_status

Get system information (version, OS, database, etc.).

---

sonarr_get_quality_profiles

Get all quality profiles available for adding series.

---

sonarr_get_language_profiles

Get all language profiles (if using v3 language profiles).

---

sonarr_get_root_folders

Get all configured root folders with disk space info.

---

sonarr_get_tags

Get all tags for organizing series.

Maintenance

sonarr_refresh_series

Refresh series information from metadata sources (TVDB). Updates episode info, air dates, etc.

Input:

• seriesId (number, required): Series ID to refresh

---

sonarr_rescan_series

Rescan series folder for files. Checks for new, modified, or deleted episode files.

Input:

• seriesId (number, required): Series ID to rescan

Common Workflows

Adding a New Series

1. Search for the series:

   sonarr_search_series with term: "Breaking Bad"
   

2. Add it to your library:

   sonarr_add_series with tvdbId from step 1
   

3. Search for episodes:

   sonarr_search_series_command with seriesId from step 2
   

Finding and Downloading Missing Episodes

1. Check wanted episodes:

   sonarr_get_wanted
   

2. Search for specific episodes:

   sonarr_search_episodes with episodeIds from step 1
   

3. Monitor the queue:

   sonarr_get_queue
   

Checking What's Coming Up

sonarr_get_calendar

Shows episodes airing in the next week by default.

Error Handling

All tools return clear error messages with context. Common errors:

• "No series found with TVDB ID X": The series doesn't exist on TVDB or the ID is wrong. Search first with sonarr_search_series.
• "No root folder configured": Add a root folder in Sonarr settings (System > Root Folders).
• "No quality profile found": Create a quality profile in Sonarr settings (Profiles > Quality).
• Connection errors: Check that SONARR_URL and SONARR_API_KEY are set correctly.

Tips for AI Agents

1. Always search first before adding - you need the correct tvdbId
2. Get configuration first (root folders, quality profiles) before adding series
3. Check health regularly to catch issues early
4. Use pagination for large libraries (get_all_series can be big!)
5. Quote from output - all tools return structured JSON with helpful notes

Development

npm run dev      # Run with tsx (hot reload)
npm run build    # Compile TypeScript
npm run start    # Run compiled version

Requirements

• Node.js 20+
• Sonarr v3 or v4 with API v3
• API key from Sonarr (Settings > General > API Key)