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

Related MCP server: MCParr Server

Installation

cd mcp-radarr
npm install
npm run build

Configuration

Set these environment variables:

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:

$env:RADARR_URL="http://localhost:7878"
$env:RADARR_API_KEY="your-api-key-here"

MCP Client Configuration

Add to your MCP client config:

{
  "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:

{
  "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

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: