sonarr

name

sonarr

description

This skill should be used when managing TV shows in Sonarr. Use when the user asks to "add a TV show", "monitor a show", "track episodes", "add season", "missing episodes", "episode not downloading", "Sonarr not finding", "search Sonarr", "find a series", "add to Sonarr", "remove a show", "check if show exists", "Sonarr library", or mentions TV show management, episode tracking, or Sonarr operations.

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.