arr-mcp

arr-mcp

Talk to your entire media stack. One server, one endpoint, one conversation.

Radarr · Sonarr · Whisparr · Lidarr · Prowlarr · Bazarr · Jellyfin · Plex · Seerr · SABnzbd · NZBGet · Transmission · qBittorrent · Profilarr · Cleanuparr · Reclaimerr · Dispatcharr · Shelfmark

Everyone else ships one MCP server per service. This is one for the stack.

That difference is the whole point, because the interesting questions live *between* services:

*"Why isn't the film I requested on Tuesday showing up in Jellyfin?"*

No single service can answer that. It spans Seerr, Radarr, Prowlarr, SABnzbd and Jellyfin — five APIs, five sets of ids, five half-answers. arr-mcp correlates them and hands back the causal chain:

diagnose { query: "Blade" }

No file on disk yet. Trigger a search in Radarr or Sonarr — nothing is

downloading and no indexer reported a failure.

One call. One answer. It even answers with a service down, and tells you which part it could not check rather than guessing across the hole.

Why people run it

Nothing else in this space does the last five at all.

Quick start — about two minutes

Also in the repo as docker-compose.example.yml. On Unraid, use unraid/arr-mcp.xml instead — a Community Applications template with the appdata path and 99:100 ownership already set. It is not listed in CA yet, so for now drop it into /boot/config/plugins/dockerMan/templates-user/ and pick it from the template list under Add Container. Steps 1 to 3 below are the same once it starts.

On Proxmox VE, proxmox/ builds an unprivileged Debian LXC from source instead — no Docker anywhere. Run it on the host, not in a guest:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/bardesss/arr-mcp/main/proxmox/ct/arr-mcp.sh)"

It defaults to 2 cores, 2 GB and 8 GB of disk — the memory is sized for the optional IMDb ingest, not for serving. config.yaml, the MCP tokens (hashed) and the databases live in /config, which an update does not touch; run update inside the container to rebuild it from the latest release. Re-running the command above on the host builds a second container instead. If it installs but never answers, journalctl -u arr-mcp is the log.

It follows the Community Scripts conventions but is not in their catalogue. One tester has reported a clean install so far (#265), and arm64 has not been tried, so the script asks rather than assuming. An install that worked is as useful to hear about as one that did not: open an issue. Steps 1 to 3 below are the same once it boots.

services:

arr-mcp: image: ghcr.io/bardesss/arr-mcp:latest container_name: arr-mcp ports:

• 6060:6060 volumes:
• ./config:/config environment:
• PUID=1000
• PGID=1000
• TZ=Europe/Amsterdam restart: unless-stopped

1. Open `http:// :6060` — the bare host, no path. Nothing to read out of the container log.

2. Claim it. The first page is a setup form rather than a sign-in: choose a username and a password of at least 12 characters.

[!IMPORTANT]

Do this before exposing the port. Until it is claimed, whoever loads that

page first owns the instance — and it holds every service's API key.

3. Add your services — Add a service, paste its URL and API key (for Plex, its X-Plex-Token; for NZBGet, Transmission and qBittorrent, its username and password; a Shelfmark with no authentication needs no key), save. It applies immediately; there is no restart. Configure only what you run. A config file that will not parse no longer takes the container down: arr-mcp serves a repair page with the error and an editor instead.

Your MCP client goes to http:// :6060/mcp with an MCP token. Create one on the config page; it is shown once, so copy it into your client straight away. Each token has its own tier and expiry, see MCP tokens. A client that can only be given a URL, not a header, can carry the token as ?token= instead — see allow_token_in_url. If you already run an identity provider, /mcp also accepts short-lived OAuth 2.1 access tokens, so each client gets its own credential and a scope that caps what it may do — read-only for one, writes for another, never more than config.yaml already permits. See auth.oauth. Everything the UI does is still just config.yaml, and editing that by hand remains supported. Clients that read the MCP Registry find it there as io.github.bardesss/arr-mcp.

Works with whatever you point at it. A client asking for Accept: application/json — or sending no Accept at all — gets one JSON object back with a Content-Length, rather than a refusal for not also naming text/event-stream. A client that does accept a stream still gets one. Even a refusal is JSON. So a plain curl works as-is, and so does a full MCP client.

Image tags are X.Y.Z, X.Y, X and latest, plus main for bleeding edge. Pin a minor — :1.51 — if you would rather approve each new tool surface yourself. Images are published for amd64 and arm64, so a Raspberry Pi or an ARM NAS runs the same build as everything else.

What you can ask it

Forty tools, but you never name them — you ask, and the model picks:

*"What's downloading right now, and is anything stuck?"*

*"What aired this week that I haven't watched?"*

*"Which of my indexers are failing, and what did they say?"*

*"Find me something highly rated from 1994 I don't already have."*

*"Go and find Dutch subtitles for the film that just landed."*

*"Not that release — grab the 1080p remux instead."*

*"Why does this episode keep failing and never downloading?"*

*"Pause SABnzbd, I need the bandwidth for an hour."*

*"What are my seeding rules, and is anything still seeding past them?"*

*"That download finished days ago and never got imported — sort it out."*

*"Put this series on the 4K profile and only monitor future seasons."*

*"This profile says it wants Dutch but keeps grabbing English — why?"*

*"Has anything in Radarr drifted from what Profilarr set?"*

*"Why is the TV guide empty, and is my IPTV subscription about to run out?"*

*"Which of my shows have metadata that does not match the files?"*

*"These episode titles are wrong for the files — fix them."*

*"Unmonitor season 5 and delete its files."* — previewed first, always.

Documentation

Requirements

• At least one supported service, LAN-reachable: Radarr 4.0+, Sonarr 4.0+, Whisparr 2.x (V2 only, not Eros), Prowlarr 1.0+, Bazarr 1.4+, Jellyfin 10.9+, Plex Media Server (no minimum enforced; verified on 1.43), Seerr 1.0+, SABnzbd 3.0+, NZBGet 21.0+, Transmission 3.0+, qBittorrent 4.1+, Profilarr 2.2.0+, Cleanuparr 2.10.0+, Reclaimerr 0.6.0+, Dispatcharr 0.33.0+, Shelfmark 1.5.0+
• Lidarr 2.1.3+ for reading, monitoring, its queue, diagnose, trigger_scan and stack_health: get_library lists its artists with their album count, monitoring and file state, get_media_details lists an artist's albums, and set_monitoring writes one album's flag or an artist's policy. Artists join to Jellyfin and Plex on the MusicBrainz artist id. get_queue, get_history and get_blocklist include Lidarr, remove_queue_item and clean_queue take a Lidarr download, and trigger_scan rescans, renames and imports for it. stack_health reports its disks, failing health checks and last library scan. No wanted list or release search yet.
• Docker, or Node 24+ to run from source
• An MCP client. Protocol revision 2026-07-28 is the native one; clients on a 2025-era revision are still served

Since 1.0 the tool surface is the public API: renaming or removing a tool, a parameter or a response field is a major, because that break is silent — a model stops finding a renamed tool rather than raising an error.

Contributing

Contributions are welcome, and new service adapters most of all — Emby and Deluge would bo