arr-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| TZ | No | Time zone, e.g. Europe/Amsterdam. | |
| PGID | No | Group ID to run the container as. | |
| PUID | No | User ID to run the container as. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
One endpoint for a self-hosted media stack: Radarr films, Sonarr series, Lidarr music, Whisparr scenes, Prowlarr indexers, Profilarr quality profiles, Bazarr subtitles, Jellyfin playback, Plex playback, Seerr requests, Grimmory books, Shelfmark book downloads, SABnzbd downloads, NZBGet downloads, Transmission downloads, qBittorrent downloads, Cleanuparr cleanup, Reclaimerr cleanup, Dispatcharr live TV.
Reading:
get_libraryis the join across your library services and media server: the only tool that can say a file one service believes in is missing from the other.diagnose_mediaanswers "why can I not play this" in one call. Prefer it over assembling that answer from several reads.Call the tool that answers the question directly. A tool's
servicefield lists the services it takes on this stack, so there is no need to callget_stack_healthfirst to find one.Every list is a window:
items,total,returned,offset,truncated.totalcounts the whole list, never the window; it is the number to report when someone asks how many.offset + returned < totalmeans there is another page; page two of 50 isoffset: 50.degradednames services that did not answer. A short list may be an outage rather than an answer, so say which it was.
Writing:
Writes happen in two calls. The first previews: read
summaryandeffects, then call again passing the returnedconfirmtoken to apply it.appliedsays which of the two just happened.dry_run: truepreviews without ever issuing a token.Most writes take a service and an id from
get_libraryorget_media_details.Read
warningsas well, and tell the user about them before confirming.A write refused for permissions names the config key that would allow it. Report that key rather than retrying.
Arguments are strict: an argument a tool does not have is refused rather than ignored, and the error lists what it does accept.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| diagnose_mediaA | Why is this not playable? Walks the chain (requested, managed, monitored, downloaded, indexed, imported, scanned) and names the first thing that explains it, with a |
| get_stack_healthA | Health of every configured service: version, disk space, failing health checks, last library scan ( |
| get_instance_optionsA | Quality profiles, root folders and tags of each Radarr, Sonarr, Whisparr and Lidarr instance: the values add_media and update_media need, so read them here, never guess. For health use get_stack_health. One row per instance: profiles with ids, root folders with free space and |
| get_indexersA | Prowlarr indexer health: which indexers are enabled, which are temporarily disabled and why, per-indexer query and grab counts, and, at detail: full, the queries indexers recently rejected (newest 50; |
| get_subtitlesA | Subtitles Bazarr knows are missing, for both films and episodes, with the languages wanted for each, and which subtitle providers are currently working, throttled, or blocked, which is usually why something is missing. Release names come from public indexers and are fenced as untrusted data. Fetch one with trigger_subtitle_search; missing films or episodes are get_wanted. |
| get_queueA | Everything downloading or stalled, merged across every *arr queue and download client, plus files waiting in Grimmory's Bookdrop. Sizes are bytes, ETAs seconds; release names are fenced as untrusted data. An *arr row carries |
| get_historyA | What happened to a download after it left the queue (grabbed, imported, failed, deleted), merged across the *arrs, SABnzbd, NZBGet, Bazarr ( |
| get_wantedA | The Radarr, Sonarr and Lidarr wanted lists. |
| get_releasesA | Runs the interactive search an *arr's own UI runs and returns every candidate, rejected ones included with their |
| get_blocklistA | Why a release keeps getting skipped. Lists what each *arr has blocklisted (releases they will not grab again) with the reason each was blocklisted, usually relayed from the download client. This is the answer to "it keeps finding the same thing and never downloading it", which |
| get_calendarA | Monitored films, episodes and albums due in a date window, merged from Radarr, Sonarr, Whisparr and Lidarr, sorted by date: upcoming and recently aired, with whether each has a file. What is already overdue is get_wanted. |
| get_playbackA | What a media-server user is watching, has next, or has watched; watch state exists only on the media server. |
| get_requestsA | Media requests in Seerr for one user. Defaults to the configured user; reading another requires allow_other_users. At |
| get_media_detailsA | Everything known about one item. A title as |
| get_metadata_issuesA | Sweeps the whole media-server library for series whose metadata does not describe the files on disk: the discovery fix_metadata cannot do, since it needs a title. Each row has |
| get_libraryA | Your library joined across Radarr, Sonarr, Whisparr, Lidarr, Grimmory and your media server on shared external ids. Use it for filtered lists and counts; for one title use get_media_details. |
| get_profile_issuesA | Faults in Radarr, Sonarr, Whisparr and Lidarr quality profiles: a minimum custom format score nothing can reach, a score set exactly on the edge, a narrower language format scored while a wider one sits at zero, a scored language the minimum does not enforce, a dialect sibling left uncovered, and Profilarr-reported drift between its saved profiles and what an instance actually holds. Each profile is checked on its own, so a finding on some profiles says nothing about which others score the same format. Drift findings are instance-scoped, not tied to any one profile, and are unaffected by the |
| search_mediaA | Search across the stack: |
| discover_mediaA | Browse what exists rather than what you have: films or series by genre, year and minimum rating, or things similar to one you know via similar_to. To find one title by name, use search_media. Answered by Seerr, TMDB-backed, so the rating is TMDB’s; similar_to needs Seerr. Without Seerr, genre/year/min_rating are answered from the local IMDb dataset, where the rating is IMDb’s. |
| trigger_searchA | Asks Radarr, Sonarr, Whisparr or Lidarr to go looking for releases for one item it already tracks, the "it never downloaded, try again" action. Takes |
| trigger_scanA | Asks a service to reconcile itself with what is on disk: the "it downloaded but will not play" fix, and the usual fix for a stale scan diagnose_media reports. No |
| trigger_subtitle_searchA | Asks Bazarr to go looking for one language of subtitles for one item it already tracks, the "it is missing Dutch subs and I do not want to wait for the next round" action. Takes |
| remove_queue_itemA | Removes one item from a download queue: the stuck-at-0%, wrong-release, or stalled download. Take |
| delete_mediaA | Removes a film from Radarr, a whole series from Sonarr, a whole site from Whisparr, a whole artist from Lidarr (by artist id, never an album id) or a book from Grimmory, optionally deleting its files from disk. Grimmory always deletes the files of a book, so it needs |
| delete_episode_filesA | Deletes the files for one Sonarr season, or for specific episodes, from disk. Destructive and not undoable. Give |
| set_monitoringA | Turns monitoring on or off. Sonarr and Whisparr: a series (by |
| respond_to_requestA | Approves or declines a pending Seerr request, or retries a failed one. Approving or retrying hands it to Radarr or Sonarr to search for and download, so it costs disk space and bandwidth even though the decision is reversible. Take |
| delete_requestA | Deletes a Seerr request record entirely. This removes the request, not the media; anything already downloaded stays on disk and in Radarr or Sonarr. Use respond_to_request with |
| add_mediaA | Adds a film to Radarr, a series to Sonarr, a site to Whisparr, an artist to Lidarr or a book to Shelfmark, and by default starts a search. A book (the search row |
| update_mediaA | Changes settings on an item already in Radarr, Sonarr or Lidarr: quality profile, root folder, monitoring, tags, Radarr's minimum availability, Sonarr's series type and rule for new seasons, Lidarr's metadata profile. The only way to change a Radarr item's monitoring. A Grimmory book is update_book. On Lidarr, |
| grab_releaseA | Grabs one release listed by get_releases (the "not that one, the 1080p remux" action) on Radarr, Sonarr, Whisparr, Lidarr or Shelfmark. Pass |
| request_mediaA | Asks Seerr for a film or series, the way a household member would through its web UI: it enters the approval queue and counts against that user's quota. This is the tool for "request X". It is not add_media: add_media writes straight into Radarr or Sonarr, skipping approval and quota entirely, and needs that service's own write permission. |
| pause_downloadsA | Pauses, resumes or throttles one download client (SABnzbd, NZBGet, Transmission or qBittorrent) or one item in its queue when |
| retry_downloadA | Retries one failed download on the usenet client that holds the files or a failed or cancelled book on Shelfmark, which queues it again if Shelfmark says it can. It picks what to send from the job itself: a SABnzbd job paused for a password is unlocked, a failed one is retried; an NZBGet download with missing articles fetches them again, and one that only failed to unpack is post-processed again. Give |
| sync_databaseA | Asks Profilarr to pull one of its databases (custom formats, quality profiles, delay profiles) from its configured git source. Safe tier: it only changes Profilarr's own store, never Radarr or Sonarr directly. |
| set_watchedA | Marks a film, series, season or episode watched or unwatched in Jellyfin or a Grimmory book read or unread. Give a |
| fix_metadataA | Repairs films and series whose media-server metadata does not describe the file on disk (a file |
| remove_blocklist_itemA | Removes one entry from an *arr's blocklist, so that release can be grabbed again. The fix for "this never downloads and I do not know why" once get_blocklist has said why. Take |
| manage_indexerA | Adds, edits, disables or re-enables one Prowlarr indexer, then syncs Prowlarr to Radarr and Sonarr. |
| update_bookA | Edits one Grimmory book by hand: title, authors, series, series number, categories ( |
| import_downloadA | Gets a finished download into the library when the *arr never took it: one stuck at |
| delete_indexerA | Deletes one Prowlarr indexer and its settings, and its copy in each app Prowlarr syncs to; apps with sync off keep a failing copy, and the preview names them. Not undoable; to stop grabs reversibly, use manage_indexer |
| blocklist_mediaA | Adds a title to, or removes it from, Seerr's blocklist (nobody can request it) or, with |
| fix_profileA | Applies a proven quality profile fix: for a certain unreachable_floor or knife_edge_floor finding from get_profile_issues, sets the profile's minimum custom format score to the total of its positive formats less the cheapest one, nothing else. Re-checks first, so a finding that no longer holds is refused, as is a profile on an instance where Profilarr syncs every profile (change it in Profilarr). The preview shows the old floor, which only a manual edit restores. Confirm to apply; returns the profile and both floors. Field reference: arr://docs/fix_profile. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| why_not_playable | Walk the whole chain for one title (requested, managed, monitored, downloaded, indexed, imported, scanned) and name the first thing that explains it. |
| whats_wrong | The periodic sweep: what is broken, stuck, out of disk, not scanning, or missing subtitles, reconciled into a short list of things that actually need you. |
| what_to_watch | Unwatched, well rated, and actually on disk, plus anything half-finished worth continuing. |
| best_in_library | Rank everything in the library by rating, watched or not. |
| whats_new | A digest: what arrived, what aired, what finished downloading and what failed. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| instances | Every configured service instance: its id, its type, and what it is permitted to do. The ids here are exactly the values other tools accept as `instance`. Mirrors get_stack_health, which answers the same thing for a client that does not surface resources. |
| health | A point-in-time verdict per service. **`get_stack_health` is the live answer**; this is a snapshot and says in `as_of` when it was taken. Read it again rather than trusting a pinned copy: a service that was reachable an hour ago may not be now. |
| library-summary | Counts across the joined library: total, on disk, and still wanted. Mirrors what get_library reports; call that for anything beyond the totals. |
| lidarr-monitoring | Every Lidarr artist's monitoring policy in one read: how many will monitor albums they discover later, and how many carry the artist-level monitor flag. `update_media` with no `id` (and `instance` when there is more than one Lidarr) is the live answer and the way to change it. The artist flag is not the album flag: an artist can read unmonitored while an album under it stays monitored, so read arr://library/summary for what is actually pending. With more than one Lidarr, `instances` reports each one that answered (one that did not is listed in `degraded`), since `update_media` writes one instance at a time, and the totals add those instances up: an artist two Lidarrs hold counts once in each. |
| docs-add_media | The full field reference for add_media: every output field and its caveats. |
| docs-diagnose_media | The full field reference for diagnose_media: every output field and its caveats. |
| docs-fix_metadata | The full field reference for fix_metadata: every output field and its caveats. |
| docs-fix_profile | The full field reference for fix_profile: every output field and its caveats. |
| docs-get_history | The full field reference for get_history: every output field and its caveats. |
| docs-get_library | The full field reference for get_library: every output field and its caveats. |
| docs-get_media_details | The full field reference for get_media_details: every output field and its caveats. |
| docs-get_metadata_issues | The full field reference for get_metadata_issues: every output field and its caveats. |
| docs-get_playback | The full field reference for get_playback: every output field and its caveats. |
| docs-get_queue | The full field reference for get_queue: every output field and its caveats. |
| docs-get_releases | The full field reference for get_releases: every output field and its caveats. |
| docs-get_wanted | The full field reference for get_wanted: every output field and its caveats. |
| docs-grab_release | The full field reference for grab_release: every output field and its caveats. |
| docs-import_download | The full field reference for import_download: every output field and its caveats. |
| docs-set_monitoring | The full field reference for set_monitoring: every output field and its caveats. |
| docs-set_watched | The full field reference for set_watched: every output field and its caveats. |
| docs-get_stack_health | The full field reference for get_stack_health: every output field and its caveats. |
| docs-trigger_scan | The full field reference for trigger_scan: every output field and its caveats. |
| docs-update_book | The full field reference for update_book: every output field and its caveats. |
| docs-update_media | The full field reference for update_media: every output field and its caveats. |
| media-cards | The poster-card view an MCP Apps host shows beside get_media_details, search_media and get_library. It renders the `cards` in their structuredContent and holds no data of its own. |
TDQS
Scored across 44 tools
Most tools have clearly distinct resource/action targets, and the descriptions explicitly separate close pairs such as get_queue vs get_history, add_media vs request_media, and search_media vs discover_media. With 44 tools there are still overlapping search/media/metadata areas, but the boundaries are documented well enough that misselection should be uncommon.
Names are consistently snake_case and generally verb-first (get_*, delete_*, update_*, trigger_*, fix_*). Minor deviations like respond_to_request and blocklist_media keep it from being perfectly uniform, but the convention is predictable.
44 tools is far above the typical well-scoped range for a single MCP server. The broad multi-service stack partially justifies the surface, but it is still heavy enough to increase selection cost and coordination burden.
The set covers a wide media-automation lifecycle: library/search, add/update/delete, monitoring, queue/history, downloads, indexers, requests, subtitles, metadata, health, and profile issues. Some peripheral operations are missing, such as full quality-profile management or richer Seerr issue handling, but core workflows have no major dead ends.