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