# Radarr MCP Server

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

## Features

- **Complete Movie Management**: Search, add, edit, and delete movies
- **Download Queue**: Monitor downloads, remove stuck items, manage blocklists
- **Calendar & Scheduling**: Track theatrical, digital, and physical releases
- **Wanted Movies**: Find and download missing movies
- **System Health**: Monitor instance health, check for issues
- **Configuration Management**: Quality profiles, root folders, tags
- **Import Exclusions**: Manage movies blocked from automatic import

## Installation

```bash
cd mcp-radarr
npm install
npm run build
```

## Configuration

Set these environment variables:

```bash
export RADARR_URL="http://localhost:7878"        # Your Radarr URL
export RADARR_API_KEY="your-api-key-here"        # Your API key (Settings > General)
```

Or on Windows:
```powershell
$env:RADARR_URL="http://localhost:7878"
$env:RADARR_API_KEY="your-api-key-here"
```

## MCP Client Configuration

Add to your MCP client config:

```json
{
  "mcpServers": {
    "radarr": {
      "command": "node",
      "args": ["<YOUR_OPENCODE_DIR>/mcp-radarr/dist/server.js"],
      "env": {
        "RADARR_URL": "http://localhost:7878",
        "RADARR_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

For development with hot reload:

```json
{
  "mcpServers": {
    "radarr": {
      "command": "npx",
      "args": [
        "tsx",
        "<YOUR_OPENCODE_DIR>/mcp-radarr/src/server.ts"
      ],
      "env": {
        "RADARR_URL": "http://localhost:7878",
        "RADARR_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## Available Tools

### Movie Management

#### `radarr_search_movies`
Search for movies by title on TMDB. Returns potential matches with metadata.

**Input:**
- `term` (string, required): Search term (e.g., "The Matrix", "Inception")

**Output:** List of matching movies with tmdbId, title, year, overview, ratings, release dates, etc.

**Note:** Use the `tmdbId` to add a movie with `radarr_add_movie`

---

#### `radarr_get_all_movies`
Get all movies in your Radarr library.

**Output:** Complete list of all movies with metadata, file status, quality, disk usage, and statistics.

---

#### `radarr_get_movie`
Get detailed information about a specific movie by its Radarr ID.

**Input:**
- `id` (number, required): Radarr movie ID

**Output:** Full movie details including file info, ratings, collection, release dates, and images.

---

#### `radarr_get_movie_by_tmdb`
Get movie information by TMDB ID.

**Input:**
- `tmdbId` (number, required): TMDB ID (e.g., 603 for The Matrix)

---

#### `radarr_add_movie`
Add a new movie to your library.

**Input:**
- `tmdbId` (number, required): TMDB ID from search results
- `monitored` (boolean, optional): Whether to monitor the movie (default: true)
- `rootFolderPath` (string, optional): Where to store the movie (uses default if not specified)
- `qualityProfileId` (number, optional): Quality profile to use (uses default if not specified)
- `minimumAvailability` (string, optional): When to download:
  - `"announced"` - Earliest (movie announcement)
  - `"inCinemas"` - When it hits theaters
  - `"released"` - Physical/digital release (default)
  - `"preDB"` - When pre-release info available
- `tags` (number[], optional): Array of tag IDs
- `addOptions.searchForMovie` (boolean, optional): Immediately search after adding (default: false)

---

#### `radarr_delete_movie`
Delete a movie from Radarr. Optionally delete files from disk.

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

**Input:**
- `id` (number, required): Movie ID to delete
- `deleteFiles` (boolean, optional): Also delete files from disk (default: false)
- `addImportExclusion` (boolean, optional): Prevent re-import (default: false)

---

#### `radarr_edit_movie`
Edit an existing movie (monitoring, quality profile, minimum availability, tags, etc.).

**Input:**
- `movie` (object, required): Complete movie object with modifications. Must include `id` field.

**Tip:** Get the full movie object first with `radarr_get_movie`, modify it, and pass it here.

### Search & Downloads

#### `radarr_search_movie`
Search for specific movies to download. This sends movies to your download client.

**Input:**
- `movieIds` (number[], required): Array of movie IDs to search for

---

#### `radarr_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")
- `includeUnknownMovieItems` (boolean, optional): Include unknown items (default: false)

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

---

#### `radarr_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 movie (default: false)
- `changeCategory` (boolean, optional): Change category in download client (default: false)

### Calendar & Missing Movies

#### `radarr_get_wanted`
Get wanted/missing movies 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: "releaseDate")
- `sortDirection` (string, optional): "ascending" or "descending" (default: "descending")

**Output:** Missing movies with release dates, ready for searching.

---

#### `radarr_get_calendar`
Get movies releasing in a date range. Great for tracking theatrical vs digital releases.

**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 movies (default: false)
- `includeMovies` (boolean, optional): Include full movie data (default: false)

**Output:** Movies grouped by release type:
- **In Cinemas**: Theatrical release dates
- **Digital**: Digital/ streaming release dates (when download typically available)
- **Physical**: Blu-ray/ DVD release dates

### System & Configuration

#### `radarr_get_health`
Get system health status. Shows warnings or errors with your Radarr instance.

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

---

#### `radarr_get_system_status`
Get system information (version, OS, database, etc.).

---

#### `radarr_get_quality_profiles`
Get all quality profiles available for adding movies.

---

#### `radarr_get_root_folders`
Get all configured root folders with disk space info.

---

#### `radarr_get_tags`
Get all tags for organizing movies.

### Movie Files

#### `radarr_get_movie_files`
Get movie file information for a specific movie.

**Input:**
- `movieId` (number, required): Radarr movie ID

**Output:** File details including quality, size, release group, and edition.

---

#### `radarr_delete_movie_file`
Delete a movie file from disk.

**⚠️ WARNING:** This permanently deletes the file!

**Input:**
- `id` (number, required): Movie file ID (from radarr_get_movie_files)

### Import Exclusions

#### `radarr_get_import_list_exclusions`
Get movies on the import exclusion list. These movies won't be imported automatically via lists.

---

#### `radarr_remove_import_list_exclusion`
Remove a movie from the import exclusion list.

**Input:**
- `id` (number, required): Import list exclusion ID (NOT the movie ID - get this from radarr_get_import_list_exclusions)

### Maintenance

#### `radarr_refresh_movie`
Refresh movie information from metadata sources (TMDB). Updates ratings, release dates, etc.

**Input:**
- `movieId` (number, required): Movie ID to refresh

---

#### `radarr_rescan_movie`
Rescan movie folder for files. Checks for new, modified, or deleted files.

**Input:**
- `movieId` (number, required): Movie ID to rescan

## Common Workflows

### Adding a New Movie

1. **Search for the movie:**
   ```
   radarr_search_movies with term: "The Matrix"
   ```

2. **Add it to your library:**
   ```
   radarr_add_movie with tmdbId from step 1
   ```

3. **Optionally search immediately:**
   ```
   radarr_add_movie with tmdbId and addOptions: { searchForMovie: true }
   ```

### Finding and Downloading Missing Movies

1. **Check wanted movies:**
   ```
   radarr_get_wanted
   ```

2. **Search for specific movies:**
   ```
   radarr_search_movie with movieIds from step 1
   ```

3. **Monitor the queue:**
   ```
   radarr_get_queue
   ```

### Tracking Upcoming Releases

```
radarr_get_calendar
```

Shows movies releasing this week with theatrical, digital, and physical release dates.

### Changing Minimum Availability

Some movies are announced years in advance. You might want to change when Radarr tries to download them:

1. **Get current movie info:**
   ```
   radarr_get_movie with id
   ```

2. **Edit and update:**
   ```
   radarr_edit_movie with modified movie object
   ```

Common values for `minimumAvailability`:
- `"announced"` - Download as soon as announced (may not exist yet!)
- `"inCinemas"` - Download when in theaters (usually cams/low quality)
- `"released"` - Download when digital/physical released (RECOMMENDED)

## Error Handling

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

- **"No movie found with TMDB ID X"**: The movie doesn't exist on TMDB or the ID is wrong. Search first with `radarr_search_movies`.
- **"No root folder configured"**: Add a root folder in Radarr settings (System > Root Folders).
- **"No quality profile found"**: Create a quality profile in Radarr settings (Profiles > Quality).
- **Connection errors**: Check that RADARR_URL and RADARR_API_KEY are set correctly.

## Tips for AI Agents

1. **Always search first** before adding - you need the correct tmdbId
2. **Get configuration first** (root folders, quality profiles) before adding movies
3. **Check health regularly** to catch issues early
4. **Use pagination** for large libraries
5. **Calendar shows release types** - digital/physical releases are when downloads become available
6. **Minimum availability matters** - "released" is usually the best choice to avoid fake/cam releases

## Development

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

## Requirements

- Node.js 20+
- Radarr v4 or v5 with API v3
- API key from Radarr (Settings > General > API Key)

## Difference from Sonarr

While both are *arr apps, there are key differences:

| Feature | Sonarr (TV) | Radarr (Movies) |
|---------|-------------|-----------------|
| Search ID | tvdbId | tmdbId |
| Seasons | Yes (multiple) | No (single file) |
| Release types | Episodes | Theatrical → Digital → Physical |
| Minimum availability | Not applicable | Important! (released vs inCinemas) |
| Language profiles | Supported | Not applicable |