radarr-mcp

Radarr MCP Server

A Model Context Protocol server that gives AI agents full access to your Radarr movie library — adding and curating movies, driving searches, and diagnosing why a download never turned into a file.

Point Claude (or any MCP client) at it and the agent can:

• Curate the library — look movies up on TMDB, add them with the right root folder and quality profile, bulk-edit monitoring, profiles and tags, and remove what you no longer want.
• Drive searches — run automatic searches, list what the indexers actually returned with their rejection reasons and custom format scores, and grab a specific release.
• Work the queue — see what is downloading, remove or blocklist a stuck grab, force pending items through, and inspect manual import candidates.
• Explain itself — history per movie, blocklist, health checks, logs, scheduled tasks, indexer and download client tests, remote path mappings, and release title parsing.

61 tools, zero install (npx), works with Claude Code, Claude Desktop, Cursor, and any other MCP client.

Example prompts

"Add Dune Part Two in 4K to my library and search for it."

"Nothing from my library has downloaded since Tuesday. Figure out what broke."

"Which monitored movies are still missing a file, and are there any releases for them right now?"

"This grab has been stuck in the queue with an import warning for two days — what happened?"

"Tag every movie from A24 as 'arthouse' and move them to the 4K profile."

"What's arriving on digital in the next month that I already have monitored?"

Install

The package is published as @orellbuehler/radarr-mcp and runs directly with npx — no clone or build needed:

claude mcp add radarr \
  --env RADARR_URL=http://radarr.local:7878 \
  --env RADARR_API_KEY=your-api-key \
  -- npx -y @orellbuehler/radarr-mcp

See Usage with Claude Code for the equivalent JSON config. For any other MCP client, run the package directly — npx -y @orellbuehler/radarr-mcp with RADARR_URL and RADARR_API_KEY set in the environment. Requires Node.js 20+.

Getting an API key

RADARR_API_KEY is Radarr's own API key: Settings → General → Security → API Key. It grants full access to the instance, so treat it like a password.

Configuration

Variable	Required	Description
RADARR_URL	yes*	Base URL of your instance, e.g. http://radarr.local:7878. A reverse-proxy path such as https://media.example.com/radarr works; /api/v3 is stripped if you include it.
RADARR_SERVER	no	Alias for RADARR_URL. Used if RADARR_URL is unset.
RADARR_API_KEY	yes	Radarr API key.

* One of RADARR_URL or RADARR_SERVER is required. The server exits at startup if the URL or the API key is missing.

Tools

Movies

Tool	Description
list_movies	Compact library listing, filtered by search term, monitoring, file state, profile or tag
get_movie	Full record for one movie
lookup_movie	Search TMDB by term, IMDB id or TMDB id
add_movie	Add a movie by TMDB id with root folder, profile and add options
update_movie	Merge-update one movie (monitoring, profile, path, tags), optionally moving files
edit_movies	Bulk-edit monitoring, profile, availability, root folder and tags
delete_movie	Remove one movie, optionally with its files
delete_movies	Remove several movies in one call

Files

Tool	Description
list_movie_files	Files with quality, size, languages and media info
delete_movie_files	Delete files from disk, leaving the movies in the library
get_rename_preview	Which files the naming config would rename, and to what
list_manual_import_candidates	Files found for a manual import, with matches and rejections

Searching and releases

Tool	Description
search_releases	Interactive indexer search with rejections and custom format scores
grab_release	Send a release to the download client
parse_release_title	Ask Radarr how it parses a release title

Queue

Tool	Description
get_queue	Paged queue with progress, warnings and import errors
get_queue_status	Queue counters (errors, warnings, unknown items)
remove_queue_items	Remove items, optionally blocklisting or skipping the redownload
grab_queue_items	Force pending items through

Activity

Tool	Description
get_calendar	Upcoming cinema, digital and physical release dates
get_history	Paged global history of grabs, imports, failures and renames
get_movie_history	Full history for one movie
mark_history_failed	Mark a grab failed, blocklist it and trigger a replacement
get_wanted	Missing or cutoff-unmet movies
get_blocklist	Blocklisted releases with the reason
remove_blocklist_items	Unblock releases

Commands

Tool	Description
run_command	Queue a command from the allowlist (searches, refresh, rescan, rename, syncs)
list_commands	Queued, running and recently finished commands
get_command	Status of one command

Settings

Tool	Description
list_quality_profiles	Profiles with cutoff and allowed qualities
get_quality_profile	One profile in full
list_root_folders	Root folders with free space and accessibility
list_tags	Tags, optionally with what uses them
create_tag / update_tag / delete_tag	Tag management
list_custom_formats	Custom formats and their specifications
list_quality_definitions	Size limits per quality
list_languages	Language ids
get_config	Read a settings section (naming, media management, …)
get_naming_examples	Example names for the current naming config

Providers

Tool	Description
list_indexers	Indexers with protocol, priority and settings (secrets redacted)
test_indexers	Test one or all indexers
list_download_clients	Download clients (secrets redacted)
test_download_clients	Test one or all download clients
list_import_lists	Import lists with their monitor and profile settings
test_import_lists	Test one or all import lists
discover_movies	Import list suggestions plus recommended/trending/popular feeds
list_notifications	Notification connections and their events
list_remote_path_mappings	Download client path → Radarr path mappings

Collections and exclusions

Tool	Description
list_collections	TMDB collections with missing-movie counts
update_collections	Bulk-update collection monitoring and add settings
list_exclusions	Import list exclusions
add_exclusion	Exclude a movie from import lists
remove_exclusions	Remove exclusions

System

Tool	Description
get_system_status	Version, branch, runtime, database, paths
get_health	Active health warnings and errors
get_disk_space	Free and total space per drive
list_tasks	Scheduled tasks with last and next run
get_updates	Available Radarr updates
get_logs	Paged log entries by level

Scope

The server manages the library, not the host. There is deliberately no tool for restarting or shutting down Radarr, restoring or deleting backups, deleting log files, or writing indexer, download client and notification definitions — those stay in the Radarr UI. Provider settings are readable and testable, and API keys and passwords are redacted from the responses.

Destructive library actions are available but never implicit: delete_movie, delete_movies and remove_queue_items default their delete_files/blocklist flags to off, and run_command only accepts commands from an allowlist.

Usage with Claude Code

{
  "mcpServers": {
    "radarr": {
      "command": "npx",
      "args": ["-y", "@orellbuehler/radarr-mcp"],
      "env": {
        "RADARR_URL": "http://radarr.local:7878",
        "RADARR_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Desktop uses the same shape in claude_desktop_config.json.

Development

npm install
npm test              # vitest
npm run lint          # eslint
npm run typecheck     # tsc --noEmit
npm run format:check  # prettier
npm run build         # tsc -> dist/
npm run spec:update   # refetch radarr-openapi.json from the Radarr repo

radarr-openapi.json is the vendored Radarr v3 API schema used as the reference when adding tools.

License

MIT