servarr-mcp
servarr-mcp is an MCP server that lets an MCP client browse, search, and manage configured Servarr apps (Sonarr, Radarr, Lidarr, Readarr, Prowlarr) through annotated read and gated write tools.
Configure only the apps you run via
<APP>_URLand<APP>_API_KEY; only those apps' tools register.Browse libraries and item details: series/episodes, movies, artists/albums/tracks, authors/books, plus lookups for new items and calendars.
Inspect operational state: queues, history, wanted/missing and cutoff items, health, disk space, quality/metadata profiles, root folders, tags, import lists, notifications, and manual-import candidates.
Search and manage downloads: live indexer release search, grabbing releases, removing queue items, re-grabbing stuck items, and marking history failed to trigger re-search.
Modify libraries: add/edit series, movies, artists, and authors; change monitoring, profiles, root folders, tags, import-list/notification state, and perform confirm-gated manual imports.
Trigger async maintenance commands such as searching for missing media, scoped searches, metadata refresh/rescans, and polling command status.
Use Prowlarr read-only tools to list indexers, view indexer stats/status, search, view history, and check health.
Rely on MCP annotations (
readOnlyHint,destructiveHint,idempotentHint) to distinguish safe reads from destructive or side-effecting writes.
Provides tools for managing movies: list movies, get details, search for new movies, view calendar, download queue, and history.
Provides tools for managing TV series: list series, get details, search for new series, list episodes, view calendar, download queue, and history.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@servarr-mcp show me the current download queue"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
servarr-mcp
· claude-fable-5-1 · 2026-11-08 · details
An MCP server for the
Servarr stack — Sonarr, Radarr, Lidarr,
Readarr, and Prowlarr — packaged as a Docker container. Lets an MCP
client (Claude Desktop, etc.) browse, search, and manage whichever
*arr apps you're running: library reads plus add/edit, queue
management, interactive release grabbing, and search/refresh
commands. Every tool carries MCP annotations (readOnlyHint,
destructiveHint, idempotentHint) so clients can distinguish and
gate the write surface.
Apps are optional: configure only the ones you actually run, and only those tools register.
Tools
Sonarr (TV)
Read:
Tool | Description |
| List all TV series tracked by Sonarr |
| Series details by ID |
| Search TVDB for a new series to add |
| List episodes for a series |
| Episode details by ID |
| Upcoming episodes |
| Current download queue |
| Compact/redacted import-list inspection |
| Compact/redacted notification and event inspection |
| Discover bounded manual-import candidates with episode/file context |
| Recent history (newest first) |
| History for one series |
| Monitored episodes with no file |
| Episodes below their quality cutoff |
| Live indexer search for candidate releases |
| Poll an async command's status |
| Health check results |
| Disk space per root folder |
| Quality profiles |
| Root folders |
| Tags |
Write:
Tool | Description |
| Add a series to the library |
| Edit a tracked series (monitoring, profile, etc.) |
| Grab a release from |
| Confirm-gated import of one exact candidate into explicit episode ids |
| Remove one queue item or a confirm-gated batch of up to 100 |
| Confirm-gated automatic-add state update |
| Confirm-gated manual-interaction event update |
| Force re-grab of a stuck queue item |
| Mark a history record failed (triggers re-search) |
| Trigger a search for missing episodes |
| Trigger a search for a whole series |
| Trigger a search for one season |
| Trigger a search for specific episodes |
| Refresh series metadata and rescan disk |
Radarr (movies)
Read:
Tool | Description |
| All movies tracked by Radarr |
| Movie details by ID |
| Search TMDB for a new movie to add |
| Look up a movie by TMDB ID |
| Look up a movie by IMDb ID |
| Upcoming movie releases |
| Current download queue |
| Compact/redacted import-list inspection |
| Compact/redacted notification and event inspection |
| Discover bounded manual-import candidates with movie/file context |
| Recent history (newest first) |
| History for one movie |
| Monitored movies with no file |
| Movies below their quality cutoff |
| Live indexer search for candidate releases |
| Poll an async command's status |
| Health check results |
| Disk space per root folder |
| Quality profiles |
| Root folders |
| Tags |
Write:
Tool | Description |
| Add a movie to the library |
| Edit a tracked movie (monitoring, profile, etc.) |
| Grab a release from |
| Confirm-gated import of one exact candidate into an explicit movie id |
| Remove one queue item or a confirm-gated batch of up to 100 |
| Confirm-gated provider/automatic-add state update |
| Confirm-gated manual-interaction event update |
| Force re-grab of a stuck queue item |
| Mark a history record failed (triggers re-search) |
| Trigger a search for missing movies |
| Trigger a search for specific movies |
| Refresh movie metadata and rescan disk |
Lidarr (music)
Read:
Tool | Description |
| All artists tracked by Lidarr |
| Artist details by ID |
| Search for a new artist to add |
| List albums (optionally per-artist) |
| Album details by ID |
| Track details |
| Track files on disk |
| Current download queue |
| Compact/redacted import-list inspection |
| Compact/redacted notification and event inspection |
| Discover bounded manual-import candidates with album/track context |
| Recent history |
| History for one artist |
| Monitored albums with no files |
| Albums below their quality cutoff |
| Live indexer search for candidate releases |
| Poll an async command's status |
| Health check results |
| Disk space per root folder |
| Quality profiles |
| Metadata profiles |
| Root folders |
| Tags |
Write:
Tool | Description |
| Add an artist to the library |
| Edit a tracked artist (monitoring, profiles, etc.) |
| Grab a release from |
| Confirm-gated import with explicit artist/album/release/track ids and replacement choice |
| Remove one queue item or a confirm-gated batch of up to 100 |
| Confirm-gated automatic-add state update |
| Force re-grab of a stuck queue item |
| Mark a history record failed (triggers re-search) |
| Trigger a search for missing albums |
| Trigger a search for an artist's albums |
| Trigger a search for specific albums |
| Refresh artist metadata and rescan disk |
Readarr (books)
Read:
Tool | Description |
| All authors tracked by Readarr |
| Author details by ID |
| Search for a new author to add |
| List books (optionally per-author) |
| Book details by ID |
| Current download queue |
| Compact/redacted import-list inspection |
| Compact/redacted notification and event inspection |
| Discover bounded manual-import candidates with book/edition context |
| Recent history |
| History for one author |
| Monitored books with no files |
| Books below their quality cutoff |
| Live indexer search for candidate releases |
| Poll an async command's status |
| Health check results |
| Disk space per root folder |
| Quality profiles |
| Metadata profiles |
| Root folders |
| Tags |
Write:
Tool | Description |
| Add an author to the library |
| Edit a tracked author (monitoring, profiles, etc.) |
| Grab a release from |
| Confirm-gated import with explicit author/book/edition ids and replacement choice |
| Remove one queue item or a confirm-gated batch of up to 100 |
| Confirm-gated automatic-add state update |
| Force re-grab of a stuck queue item |
| Mark a history record failed (triggers re-search) |
| Trigger a search for missing books |
| Trigger a search for an author's books |
| Trigger a search for specific books |
| Refresh author metadata and rescan disk |
Prowlarr (indexer manager)
Read-only:
Tool | Description |
| All configured indexers |
| Per-indexer query/grab stats |
| Indexer health / disabled status |
| Search across enabled indexers |
| Recent history (queries, grabs) |
| Health check results |
Related MCP server: Arr-MCP
Configuration
Each app uses two environment variables. Set both for an app to enable its tools; leave them unset to skip the app entirely.
App | URL var | API key var | Default port |
Sonarr |
|
| 8989 |
Radarr |
|
| 7878 |
Lidarr |
|
| 8686 |
Readarr |
|
| 8787 |
Prowlarr |
|
| 9696 |
API keys are found under each app's Settings → General → API Key.
At least one app must be configured or the server exits with an error.
Same-host deployments
When the *arr apps run on the same Docker host as this container
(typical home-lab setup), don't use the host's hostname (e.g.
my-nas) in the *_URL vars — Docker's DNS context can't resolve
the host's own name from inside a container. Use
http://host.docker.internal:<port> instead. The provided
docker-compose.yml already maps host.docker.internal to the host
gateway via extra_hosts, so this works on Linux Docker too (not
just Docker Desktop).
Run with Docker
docker build -t servarr-mcp .
docker run -i --rm \
-e SONARR_URL=http://192.168.1.50:8989 -e SONARR_API_KEY=... \
-e RADARR_URL=http://192.168.1.50:7878 -e RADARR_API_KEY=... \
-e PROWLARR_URL=http://192.168.1.50:9696 -e PROWLARR_API_KEY=... \
servarr-mcpPublished image
After each push to main, GitHub Actions builds and pushes a multi-arch
image to GHCR:
ghcr.io/carldog/servarr-mcp:latest (linux/amd64 + linux/arm64)
Pull instead of building locally:
docker pull ghcr.io/carldog/servarr-mcp:latest
docker run -i --rm \
-e SONARR_URL=... -e SONARR_API_KEY=... \
ghcr.io/carldog/servarr-mcp:latestRun with Docker Compose (HTTP, long-lived)
The compose file runs the server in HTTP mode (Streamable HTTP) for
long-lived deployment via Portainer or Compose. It pulls the published
image from ghcr.io/carldog/servarr-mcp:latest.
# Set whichever app credentials apply:
export SONARR_URL=http://192.168.1.50:8989; export SONARR_API_KEY=...
export RADARR_URL=http://192.168.1.50:7878; export RADARR_API_KEY=...
# ... (other apps as needed)
export HOST_PORT=3002 # optional, defaults to 3002
docker compose upThe MCP endpoint will be at http://<host>:${HOST_PORT}/mcp.
Deploy via Portainer (Stack from Git)
In Portainer, Stacks → Add Stack → Repository.
Repository URL:
https://github.com/CarlDog/servarr-mcpCompose path:
docker-compose.ymlEnvironment variables: set whichever
<APP>_URL/<APP>_API_KEYpairs apply, plus optionallyHOST_PORT.Deploy. Healthcheck reaches green within ~10 seconds.
Use with Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"servarr": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "SONARR_URL", "-e", "SONARR_API_KEY",
"-e", "RADARR_URL", "-e", "RADARR_API_KEY",
"-e", "PROWLARR_URL", "-e", "PROWLARR_API_KEY",
"servarr-mcp"
],
"env": {
"SONARR_URL": "http://192.168.1.50:8989",
"SONARR_API_KEY": "...",
"RADARR_URL": "http://192.168.1.50:7878",
"RADARR_API_KEY": "...",
"PROWLARR_URL": "http://192.168.1.50:9696",
"PROWLARR_API_KEY": "..."
}
}
}
}Repeat the -e and env block patterns for whichever apps you run.
Local development
npm install
cp .env.example .env # then edit
SONARR_URL=... SONARR_API_KEY=... npm run devSecurity
The container runs as a non-root user (
servarr).API keys are passed via env vars — never bake them into the image.
A
.githooks/pre-commitruns gitleaks on every commit. Activate it once per clone:git config core.hooksPath .githooks.
Available Tools
29 toolssonarr_add_seriesSonarr: Add SeriesA
Add a new series to Sonarr by TVDB id. Internally calls /series/lookup to fetch the full series metadata, then POSTs /series with the merged body. Returns the created SeriesResource. Workflow: call sonarr_lookup_series first to get the tvdbId, sonarr_list_quality_profiles for quality_profile_id, sonarr_list_root_folders for root_folder_path. Note: search_for_missing_episodes defaults to false here — Sonarr's server-side default is true, which may immediately hit indexers; flip explicitly if you want that.
Inputs: tvdb_id (required), quality_profile_id (required), root_folder_path (required), monitored, +3 more.
sonarr_calendarSonarr: CalendarARead-only
Get upcoming/recent episodes from Sonarr's calendar within an ISO date window. Use for 'what's airing this week?' queries. Movies live in radarr_calendar; Lidarr/Readarr/Prowlarr have no calendar surface.
Inputs: start, end.
sonarr_diskspaceSonarr: Disk SpaceARead-only
Get per-mount disk space (free/total bytes) seen by Sonarr. Useful for 'where do I have room to add this?' decisions; pair with sonarr_list_root_folders to map paths to capacity.
Inputs: no named parameters.
sonarr_edit_seriesSonarr: Edit SeriesADestructiveIdempotent
Edit settings on an existing Sonarr series. Internally GETs the current SeriesResource, applies your changes, and PUTs the full resource back. Pass only the fields you want to change — others are preserved. WARNING: changing root_folder_path moves files on disk; watch your storage and download client.
Inputs: id (required), monitored, quality_profile_id, root_folder_path, +2 more.
sonarr_get_commandSonarr: Get Command StatusARead-only
Poll the status of an async command queued by sonarr_search_*, sonarr_refresh_series, etc. Returns the current CommandResource (status: queued|started|completed|failed, exception, started/ended timestamps).
Inputs: id (required).
sonarr_get_episodeSonarr: Get EpisodeARead-only
Get full details for a single Sonarr episode by ID — air date, overview, file info, monitored state, etc.
Inputs: id (required).
sonarr_get_seriesSonarr: Get SeriesARead-only
Get full details for a Sonarr series by id — overview, cast, seasons, episode counts, file paths. Drill-down companion to sonarr_list_series and sonarr_lookup_series.
Inputs: id (required).
sonarr_grab_releaseSonarr: Grab ReleaseA
HIGH RISK. Immediately queues a download from the indexer for the given release. Pass the release object verbatim from sonarr_release_search output — Sonarr looks the release up server-side by guid+indexerId, so the cache must still be warm (re-run release_search if the grab fails with a 'not found' error). If the release was rejected by the quality profile, set should_override to true to grab anyway.
Inputs: release (required), should_override.
sonarr_healthSonarr: HealthARead-only
Get aggregated Sonarr health warnings (indexer down, low disk, etc.). Summary view; for actionable per-indexer failure detail (which indexers, since when, why) use prowlarr_indexer_status.
Inputs: no named parameters.
sonarr_historySonarr: HistoryARead-only
Get recent Sonarr history (newest first). For per-resource scope use sonarr_history_series. To re-trigger a search for a wrong-grab event, use sonarr_history_mark_failed.
Inputs: page_size.
sonarr_history_mark_failedSonarr: Mark History FailedADestructiveIdempotent
Mark a Sonarr history entry as failed. Triggers Sonarr to re-search for a replacement on the next interval. Useful when an episode imported as the wrong cut/quality/release. Returns a confirmation; no body from the *arr API.
Inputs: id (required).
sonarr_history_seriesSonarr: Series HistoryARead-only
Get history scoped to a single series — every grab/import/upgrade/delete event. Much narrower than sonarr_history, which is server-wide and routinely runs into hundreds of thousands of records.
Inputs: series_id (required).
sonarr_list_episodesSonarr: List EpisodesARead-only
List every episode for a Sonarr series. Returns episode ids you can drill into with sonarr_get_episode or pass to sonarr_release_search / sonarr_search_episode.
Inputs: series_id (required).
sonarr_list_quality_profilesSonarr: List Quality ProfilesARead-only
List Sonarr quality profiles. The id is required as qualityProfileId when adding a series.
Inputs: no named parameters.
sonarr_list_root_foldersSonarr: List Root FoldersARead-only
List Sonarr root folders (where series are stored on disk). The path is required as rootFolderPath when adding a series.
Inputs: no named parameters.
sonarr_list_seriesSonarr: List SeriesARead-only
List TV series tracked by Sonarr as a paged result. Default returns slim fields per series (id, title, year, monitored, tvdbId, imdbId, tmdbId, qualityProfileId, tags, path, network, status, ended, nextAiring, previousAiring, runtime, seasonFolder, statistics — statistics carries seasonCount / episodeFileCount / episodeCount / sizeOnDisk); set verbose=true for the full SeriesResource. Sonarr's upstream /series returns the entire library in one shot — paging here is server-side. For full details on one series (including all seasons), use sonarr_get_series. To find a series NOT yet tracked, use sonarr_lookup_series (TVDB metadata).
Inputs: page, page_size, verbose.
sonarr_list_tagsSonarr: List TagsARead-only
List Sonarr tags (label + id pairs). Useful for scoping queries by tag (e.g. 'show me everything tagged kids') and for setting tag ids on add/edit operations.
Inputs: no named parameters.
sonarr_lookup_seriesSonarr: Lookup Series (TVDB)ARead-only
Fuzzy search TVDB for a series to potentially add. Returns SeriesResource with tvdbId etc., suitable for sonarr_add_series. Searches TVDB's catalogue, NOT your tracked library — use sonarr_list_series / sonarr_get_series for what's already tracked.
Inputs: term (required).
sonarr_queueSonarr: QueueARead-only
Get the current Sonarr download queue, paged. Default returns the first 20 records. Bump page_size or step through pages when the queue is large.
Inputs: page, page_size.
sonarr_queue_regrabSonarr: Re-grab Queue ItemA
Force Sonarr to re-grab a stuck queue item from the indexer. Useful when a download is hung or the file is corrupt. Returns the updated queue entry.
Inputs: id (required).
sonarr_queue_removeSonarr: Remove from QueueADestructiveIdempotent
Remove a single item from Sonarr's download queue. All four flags are exposed because the server-side defaults are not obviously safe — in particular, removeFromClient defaults to true on Sonarr's side, which deletes the file from the download client. This tool defaults remove_from_client to false; flip it explicitly if you want the file gone.
Inputs: id (required), remove_from_client, blocklist, skip_redownload, +1 more.
sonarr_refresh_seriesSonarr: Refresh Series MetadataAIdempotent
Trigger Sonarr to re-pull metadata from TVDB for one series (cast, episode list, artwork). Async — returns the queued CommandResource. Poll status with sonarr_get_command (use the returned id).
Inputs: series_id (required).
sonarr_release_searchSonarr: Release SearchARead-only
Run a live indexer search for releases of a specific series, season, or episode and return candidate ReleaseResource entries (without grabbing). Hits every enabled indexer in real time — slow and rate-limit-sensitive, so call only when the user wants to pick a release manually. Pass series_id for the whole series, season_number to scope to a season, or episode_id to scope to a single episode. At least one is required. Returned items feed sonarr_grab_release (when it ships).
Inputs: series_id, episode_id, season_number.
sonarr_search_episodeSonarr: Search EpisodesAIdempotent
Trigger Sonarr to search indexers for one or more specific episodes. Async — returns the queued CommandResource. Poll status with sonarr_get_command (use the returned id).
Inputs: episode_ids (required).
sonarr_search_missingSonarr: Search Missing EpisodesAIdempotent
Trigger Sonarr to search indexers for all monitored, missing episodes. Async — returns the queued CommandResource (id, status); the actual search runs in the background. Poll status with sonarr_get_command (use the returned id).
Inputs: no named parameters.
sonarr_search_seasonSonarr: Search SeasonAIdempotent
Trigger Sonarr to search indexers for one season of one series. Async — returns the queued CommandResource. Poll status with sonarr_get_command (use the returned id).
Inputs: series_id (required), season_number (required).
sonarr_search_seriesSonarr: Search SeriesAIdempotent
Trigger Sonarr to search indexers for all monitored, missing episodes of one series. Async — returns the queued CommandResource. Poll status with sonarr_get_command (use the returned id).
Inputs: series_id (required).
sonarr_wanted_cutoffSonarr: Wanted (Below Cutoff)ARead-only
List episodes downloaded below cutoff quality — upgrade candidates. Filters to monitored items by default. Items here are upgrade candidates; trigger a re-search with sonarr_search_missing (which also picks up cutoff-unmet items by default).
Inputs: page_size, monitored.
sonarr_wanted_missingSonarr: Wanted (Missing)ARead-only
List episodes that are wanted but not yet downloaded. Filters to monitored items by default. Once you've identified what's missing, trigger an indexer hunt with sonarr_search_missing.
Inputs: page_size, monitored.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 29 tools
Each tool targets a distinct action on a specific entity (series, episode, queue, history, etc.), with clear scoping differences (e.g., sonarr_list_series vs sonarr_lookup_series, sonarr_history vs sonarr_history_series). No two tools appear to do the same thing.
All tools follow a consistent verb_noun pattern with 'sonarr_' prefix (e.g., sonarr_add_series, sonarr_list_episodes, sonarr_get_command). No mixing of naming conventions.
29 tools for a full-featured media management server is slightly high but justified given the breadth of operations (CRUD, search, queue, history, system). Each tool serves a distinct purpose without unnecessary duplication.
Covers core workflows: adding/editing series, managing episodes, queue control, history, health checks, and system info. Missing a delete series tool and some edge-case operations, but the surface is largely complete for typical usage.
Maintenance
Related MCP Connectors
One MCP server for all web data. Scrape, search, crawl, and AI research in one install.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Hosted MCP server for live public-data APIs and Skills for AI agents.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server for managing a media server stack (Plex, Radarr, Overseerr, Bazarr, Prowlarr, Trakt.tv) using natural language to browse, request, and discover content.12MIT
- AlicenseAqualityCmaintenanceMCP server to manage your *ARR media stack (Radarr, Sonarr, Lidarr, Readarr, Prowlarr) for searching, adding, and managing movies, TV shows, music, books, and indexers.1ISC
- FlicenseNot gradedqualityDmaintenanceA remote MCP server for managing your arr stack (Sonarr, Radarr, qBittorrent, Seerr) via Claude.ai on mobile, enabling you to fix bad downloads, block release groups, request new content, and check trending.-
- AlicenseNot gradedqualityDmaintenanceMCP server that enables local LLMs to manage a home media stack including Radarr, Sonarr, Prowlarr, and others.MIT