Arr Mcp

What is Arr Mcp about?

Arr Mcp centralizes the management of a home media ecosystem by exposing one MCP server that talks to all supported tools (Radarr, Sonarr, Whisparr, Prowlarr, Bazarr, Jellyfin, Plex, Seerr, SABnzbd, Transmission, qBittorrent, Profilarr). It correlates information across services, allowing queries that span the whole stack and returning a single, actionable response.

How to use Arr Mcp?

1. Deploy the Docker image ghcr.io/bardesss/arr-mcp:latest (or run from source with Node 24+). Example compose snippet is provided in the README.
2. Access http://<host>:6060 to claim the instance with a strong username/password.
3. Add each media service via the web UI – supply the service URL and API key/token.
4. Generate an MCP token on the config page; use this token when calling the /mcp endpoint (as a bearer token, query parameter, or OAuth 2.1 token).
5. Send MCP requests (e.g., diagnose { query: "Blade" }) using any client that supports the Model Context Protocol.

Key Features of Arr Mcp

• Cross‑service diagnostics – single query reveals why a media item is missing, tracing through request, download, import, and playback layers.
• Quality profile validation – evaluates Profilarr rules mathematically and suggests concrete fixes.
• Secure write operations – writes are opt‑in, previewed, confirmed, and audited.
• Web‑based config UI – add/remove services, view logs, audit trail, and test connectivity without editing YAML.
• Unified vocabulary – all tools share the same list/page format and error handling.
• Extensible tool set – 39 built‑in tools covering monitoring, searching, downloading, metadata fixing, and more.
• Multi‑architecture Docker images – works on amd64 and arm64 (e.g., Raspberry Pi).
• Optional IMDb ingest – enriches series data with IMDb scores.

Use Cases of Arr Mcp

• Automated troubleshooting – ask why a new film hasn't appeared in Plex; receive the exact failing service and recommended action.
• Policy enforcement – ensure downloads respect quality profiles defined in Profilarr, with automatic correction suggestions.
• Batch operations – preview and execute bulk actions such as unmonitoring seasons, deleting files, or pausing SABnzbd.
• Dashboard monitoring – view live status, latency, and version information for every configured service.
• Custom client integration – any MCP‑compatible client (including LLM‑based assistants) can query or command the stack through a single endpoint.

FAQ from the Arr Mcp

• Do I need to expose the server to the internet? No. It is intended for LAN use; if remote access is required, place it behind a TLS‑terminated reverse proxy and restrict allowed hosts.
• Can I run multiple instances? Yes, each instance uses its own config.yaml and token set. Ensure each instance is claimed with unique credentials.
• What if a service is down? Arr Mcp reports the specific service that could not be reached and continues to provide information from the others.
• Are writes safe? Writes are disabled by default. When enabled, every operation is previewed, requires explicit confirmation, and is logged in an audit trail.
• How are API keys protected? Keys are stored hashed in config.yaml and never exposed over the MCP endpoint; the UI only shows masked values.
• Can I add new services? Yes, adapters can be contributed for services like Lidarr, Emby, or Deluge following the contribution guidelines.
• Which platforms are supported? Docker on any OS that can run amd64/arm64 containers, as well as direct Node execution on Linux/macOS/Windows.

arr-mcp

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

Radarr · Sonarr · Whisparr · Prowlarr · Bazarr · Jellyfin · Plex · Seerr · SABnzbd · Transmission · qBittorrent · Profilarr

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

🔍 diagnose answers what no single service can	Walks the whole chain — requested, managed, monitored, downloaded, indexed, imported, scanned — and names the first thing that explains the absence.
🧮 Quality profiles that cannot do what they say	A minimum score nothing can reach, a language preferred but never required, a format scored where its wider twin sits at zero. The arithmetic ones are proved rather than guessed, and every fix names a change to make in Profilarr, which owns them.
🛡️ Indexer text is data, never instruction	Release names from public indexers are attacker-controllable and flow straight into model context. arr-mcp fences every one of them.
✋ Writes are opt-in, previewed, recorded	Off until you turn them on, per service. Every write shows you exactly what it would do and waits for confirmation — and lands in an audit trail either way.
🖥️ A config page that diagnoses	Add services from a browser, see what is broken and what to do about it, read the logs and the write audit. No YAML required.
📚 Thirty-nine tools, one vocabulary	Every list pages the same way and answers readably whether or not your client reads structuredContent, every error names the config key that would fix it, every write takes ids rather than titles.

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, and it has never been run on a real host — arm64 least of all, so the script asks rather than assuming. An install that worked is as useful to hear about as one that did not: #265. 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://<host>: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 Transmission and qBittorrent, its username and password), 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://<host>: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.6 — 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

Thirty-eight 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?" "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

Tools	All thirty-nine, what each answers, and the fields whose meaning is not obvious
Writes	Turning them on, the two tiers, and the preview-and-confirm handshake
Configuration	config.yaml, the seven services that take a list, Jellyfin's default_user
Config UI	The four pages, and what each does that is not obvious
Management API	JSON API for companion apps to see and manage services and tokens, with a key you generate on the config page
IMDb ratings	The only way to get an IMDb score for a series, and what it costs
Security	The threat model, walked against the OWASP MCP Top 10, including what it does not solve
Contributing	Which services qualify, how to add an adapter, and the rules an AI agent tends to break

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 1.32+, Seerr 1.0+, SABnzbd 3.0+, Transmission 3.0+, qBittorrent 4.1+, Profilarr 2.2.0+
• Docker, or Node 24+ to run from source
• An MCP client speaking protocol revision 2026-07-28

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 — Lidarr, Emby and Deluge would all be accepted today, and the list says so in advance, along with the ones that would not be. An adapter is deliberately the most self-contained thing in the codebase. Two things to know first: not every service qualifies, and the bar is written down rather than decided per pull request — which services qualify. And I cannot test a service I do not run, so the second bar is that you tested it against your own live instance and the PR says what you tested and against which version.

One adapter remains unverified: qBittorrent. The maintainer runs neither Plex nor qBittorrent — testing means running a build against your own server and reporting what worked. Plex has since been verified against two live Plex Media Servers by two volunteer testers, its first write included. Its metadata repair has fixed films on a live server but not yet series, so it still ships off by default (#312); qBittorrent has shipped but still waits on the same kind of report. The design behind Plex, and what else is on the list.

AI-assisted contributions are welcome, held to the same bar and no other; arr-mcp is itself built with a coding agent. Point yours at CONTRIBUTING.md.

Missing a tool? Open an issue describing the question you could not get answered rather than the tool you think should exist. Often the answer is a new parameter on one that already exists — and when it genuinely needs a new tool, the question is what tells us so.

Security

arr-mcp is not designed to be exposed to the internet. The /mcp endpoint requires a bearer token because "LAN-only" is a network assumption rather than a security control — it fronts every service credential you configure and, once enabled, file deletion, and a home network contains guest phones and IoT devices. Put it behind a reverse proxy with TLS if it needs to leave the LAN, and pin allowed_hosts if you do.

Beyond the network: writes are off until you enable them, every write is previewed and confirmed before it acts, and everything a service returns is fenced as data rather than instruction. Security walks all of it against the OWASP MCP Top 10 — and is equally explicit about what it does not solve. Found something? SECURITY.md.

Thanks

arr-mcp is glue; the hard parts belong to other people. Nearly every service it speaks to is free software maintained largely by volunteers — Radarr, Sonarr, Whisparr, Prowlarr, Bazarr, Jellyfin, Seerr, SABnzbd, Transmission, qBittorrent, Profilarr — as are the libraries it is built on: MCP TypeScript SDK, Hono, Zod, Pino, Vitest, yaml and TypeScript. If you find arr-mcp useful, consider supporting them first. Plex is the exception: a commercial product, but its API carries as much of the work as the rest.

When you enable the IMDb dataset: information courtesy of IMDb, used with permission, for personal and non-commercial use.

Licence

MIT