Radarr

---
name: radarr
description: This skill should be used when managing movies in Radarr. Use when the user asks to "add a movie", "download a movie", "grab a movie", "monitor a movie", "movie not downloading", "Radarr can't find it", "search Radarr", "find a film", "add to Radarr", "remove a movie", "add movie collection", "check if movie exists", "Radarr library", or mentions movie management, TMDB integration, or Radarr operations.
---

# Radarr Movie Management Skill

Search and add movies to your Radarr library with support for collections, quality profiles, and search-on-add.

## Purpose

This skill enables management of your Radarr movie library:
- Search for movies by name
- Add individual movies or entire collections
- Check if movies already exist
- Remove movies (with optional file deletion)
- View quality profiles and root folders

Operations include both read and write actions. **Always confirm before removing movies 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.

```bash
RADARR_URL="http://localhost:7878"
RADARR_API_KEY="your-api-key"
RADARR_DEFAULT_QUALITY_PROFILE="1"  # Optional (defaults to 1)
```

- `RADARR_URL`: Your Radarr server URL (no trailing slash)
- `RADARR_API_KEY`: API key from Radarr (Settings → General → API Key)
- `RADARR_DEFAULT_QUALITY_PROFILE`: Quality profile ID (optional, run `config` command to see options)

## Commands

All commands return JSON output.

### Search for Movies

```bash
bash skills/radarr/scripts/radarr search "Inception"
bash skills/radarr/scripts/radarr search "The Matrix"
```

**Output:** Numbered list with TMDB IDs, titles, years, and collection info.

```bash
# Raw JSON (for capturing TMDB IDs programmatically)
bash skills/radarr/scripts/radarr search-json "Inception"
```

### Check if Movie Exists

```bash
bash skills/radarr/scripts/radarr exists <tmdbId>
```

**Output:** `"not_found"` if absent; `"exists"` plus a detail line (ID, title, hasFile) if present.

### Add a Movie

```bash
bash skills/radarr/scripts/radarr add <tmdbId>                        # Searches immediately (default)
bash skills/radarr/scripts/radarr add <tmdbId> <profileId>            # Use specific quality profile
bash skills/radarr/scripts/radarr add <tmdbId> --no-search            # Add without searching
```

### Add Full Collection

```bash
bash skills/radarr/scripts/radarr add-collection <collectionTmdbId>
bash skills/radarr/scripts/radarr add-collection <collectionTmdbId> --no-search
```

If the collection can't be found by ID, provide a search term:
```bash
bash skills/radarr/scripts/radarr add-collection <collectionTmdbId> "Lord of the Rings"
bash skills/radarr/scripts/radarr add-collection <collectionTmdbId> "Lord of the Rings" --no-search
```

### Collection Info

```bash
bash skills/radarr/scripts/radarr collection-info <collectionTmdbId>
```

Returns metadata for a collection (title, monitored status, movies list) — does not add anything.

Adds all movies in a collection (e.g., all Lord of the Rings movies).

### Remove a Movie

```bash
bash skills/radarr/scripts/radarr remove <tmdbId>                # Keep files
bash skills/radarr/scripts/radarr remove <tmdbId> --delete-files # Delete files too
```

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

### Get Configuration

```bash
bash skills/radarr/scripts/radarr config
```

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

## Workflow

When the user asks about movies:

1. **"Add Inception to Radarr"** → Run `search "Inception"`, present results with TMDB links, then `add <tmdbId>`
2. **"Is Dune in my library?"** → Run `exists <tmdbId>`
3. **"Add all Star Wars movies"** → Search for collection, then `add-collection <collectionId>`
4. **"Remove The Matrix"** → Ask about file deletion, then run `remove <tmdbId>` with appropriate flag
5. **"What quality profiles do I have?"** → Run `config`

### Presenting Search Results

Always include TMDB links when presenting search results:
- Format: `[Title (Year)](https://themoviedb.org/movie/ID)`
- Show numbered list for user selection
- Include year and brief overview

### Adding Movies

1. Search for the movie
2. Present results with TMDB links
3. User picks a number
4. **Collection check:** If movie is part of a collection, ask if they want the whole collection
5. Add movie or collection (searches immediately by default)

## Parameters

### add command
- `<tmdbId>`: TMDB ID of the movie (required)
- `[profileId]`: Optional quality profile ID (positional, before `--no-search`); defaults to `RADARR_DEFAULT_QUALITY_PROFILE` or first available
- `--no-search`: Don't search for movie after adding

### add-collection command
- `<collectionTmdbId>`: TMDB ID of the collection (required)
- `[searchTerm]`: Optional search term if collection can't be resolved by ID (positional)
- `--no-search`: Don't search for movies after adding

### remove command
- `<tmdbId>`: TMDB ID of the movie (required)
- `--delete-files`: Also delete media files (default: keep files)

## Notes

- Requires network access to your Radarr server
- Uses Radarr API v3
- All data operations return JSON
- Quality profile IDs vary by installation — use `config` to discover yours
- The `defaultQualityProfile` from config is used when adding movies
- Collections are TMDB-specific and include related movies (sequels, franchises)

## Reference

- [Radarr API Documentation](https://radarr.video/docs/api/)
- [TMDB](https://themoviedb.org/) — The Movie Database

For detailed local reference, see:
- **[API Endpoints](./references/api-endpoints.md)** - Complete endpoint reference with parameters
- **[Quick Reference](./references/quick-reference.md)** - Common operations with copy-paste examples
- **[Troubleshooting](./references/troubleshooting.md)** - 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.