Sonarr TV Show Management Skill

Search and add TV shows to your Sonarr library with support for monitor options, quality profiles, and search-on-add.

Purpose

This skill enables management of your Sonarr TV show library:

• Search for TV shows by name
• Add shows to your library with configurable options
• Check if shows already exist
• Remove shows (with optional file deletion)
• View quality profiles and root folders

Operations include both read and write actions. Always confirm before removing shows with file deletion.

Setup

Add credentials to ~/.config/overseerr-mcp/.env (or ~/.config/overseerr-mcp/.env). Run the config-media-stack skill to configure automatically.

SONARR_URL="http://localhost:8989"
SONARR_API_KEY="<your_api_key>"
SONARR_DEFAULT_QUALITY_PROFILE="1"  # Optional: defaults to 1 if not set

Configuration variables:

• SONARR_URL: Your Sonarr server URL (no trailing slash)
• SONARR_API_KEY: API key from Sonarr (Settings → General → API Key)
• SONARR_DEFAULT_QUALITY_PROFILE: Quality profile ID (optional, defaults to 1)

Commands

All commands return JSON output.

Search for Shows

bash skills/sonarr/scripts/sonarr search "Breaking Bad"
bash skills/sonarr/scripts/sonarr search "The Office"

Output: Numbered list with TVDB IDs, titles, years, and TVDB links.

# Raw JSON (for capturing TVDB IDs programmatically)
bash skills/sonarr/scripts/sonarr search-json "Breaking Bad"

Check if Show Exists

bash skills/sonarr/scripts/sonarr exists <tvdbId>

Output: "not_found" if absent; "exists" plus a detail line (ID, title, season count) if present.

Add a Show

bash skills/sonarr/scripts/sonarr add <tvdbId>                            # Searches immediately (default)
bash skills/sonarr/scripts/sonarr add <tvdbId> <profileId>                # Use specific quality profile
bash skills/sonarr/scripts/sonarr add <tvdbId> --no-search                # Add without searching
bash skills/sonarr/scripts/sonarr add <tvdbId> <profileId> --no-search    # Profile + no search

Note: Always monitors all seasons (monitor: "all"). For finer-grained season control, use the Sonarr UI after adding.

Remove a Show

bash skills/sonarr/scripts/sonarr remove <tvdbId>                # Keep files
bash skills/sonarr/scripts/sonarr remove <tvdbId> --delete-files # Delete files too

Important: Always ask the user if they want to delete files when removing!

Get Configuration

bash skills/sonarr/scripts/sonarr config

Output: Available root folders and quality profiles with their IDs.

Workflow

When the user asks about TV shows:

1. "Add Breaking Bad to Sonarr" → Run search "Breaking Bad", present results with TVDB links, then add <tvdbId>
2. "Is The Office in my library?" → Run exists <tvdbId>
3. "Remove Game of Thrones" → Ask about file deletion, then run remove <tvdbId> with appropriate flag
4. "What quality profiles do I have?" → Run config

Presenting Search Results

Always include TVDB links when presenting search results:

• Format: [Title (Year)](https://thetvdb.com/dereferrer/series/<tvdbId>) (use the numeric TVDB ID from search output)
• Show numbered list for user selection
• Include year and brief overview

Adding Shows

1. Search for the show
2. Present results with TVDB links
3. User picks a number
4. Add show (searches for episodes by default)

Parameters

add command

• <tvdbId>: TVDB ID of the show (required)
• [profileId]: Optional quality profile ID (positional, before --no-search); defaults to SONARR_DEFAULT_QUALITY_PROFILE or first available
• --no-search: Don't search for episodes after adding

remove command

• <tvdbId>: TVDB ID of the show (required)
• --delete-files: Also delete media files (default: keep files)

Notes

• Requires network access to your Sonarr server
• Uses Sonarr API v3
• All data operations return JSON
• Quality profile IDs vary by installation — use config to discover yours
• The SONARR_DEFAULT_QUALITY_PROFILE from .env is used when adding shows (defaults to 1)

Reference

• Sonarr API Documentation
• TVDB — TV show database

For detailed local reference, see:

• API Endpoints - Complete endpoint reference with parameters
• Quick Reference - Common operations with copy-paste examples
• Troubleshooting - Authentication, connection, and error solutions

---

Agent Tool Usage Requirements

When running script commands via the zsh tool, always pass pty: true — without it, command output will be suppressed even though the command executes successfully.