arr-mcp

A small Model Context Protocol server that puts the *arr media stack (Sonarr, Radarr, Prowlarr, Jellyseerr, Bazarr) behind clean, typed tools. An MCP client such as Claude calls those tools directly over each app's REST API — no browser, no screen-scraping, no VPN into the LAN.

The server holds the API keys itself; the client never sees them. It runs on the .104 docker host and is reached from the cloud over an authenticated Cloudflare Tunnel, so it works whether you're home or driving Claude from your phone.

Why this exists

Everything Claude previously did on the media stack went through a browser extension on the Mac — which brought connection-identity churn ("which browser?"), session/2FA friction, and the VPN + remote-control dance. This server removes the browser and the Mac from the loop entirely, and replaces UI scraping with fast, structured API calls.

Related MCP server: mcp-arr-suite

Tools

* = write action (triggers a search, or clears a series' blocklist). Everything else is read-only. There are deliberately no delete/remove or config-mutation tools — that keeps the blast radius small. Add more later as needed.

Setup

cp config.example.env .env
# edit .env: real API keys (Settings > General > Security > API Key in each app)
# and a strong MCP_AUTH_TOKEN:  python3 -c "import secrets; print(secrets.token_urlsafe(48))"

docker compose up -d --build

Quick local check (should return a 400/406 about a missing MCP session — that means it's up and your token was accepted; a 401 means the token is wrong):

curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer <your MCP_AUTH_TOKEN>" \
  http://localhost:8787/mcp

Run without Docker (for development)

pip install -r requirements.txt
set -a; source .env; set +a
python server.py

Exposing it to Claude

The MCP endpoint is https://<your-hostname>/mcp.

1. Tunnel it. Either uncomment the cloudflared service in docker-compose.yml and give it its own tunnel, or add a hostname to your existing Jellyfin tunnel pointing at http://arr-mcp:8787 (or http://localhost:8787 from the host). Put Cloudflare Access in front of the hostname, or rely on the bearer token — ideally both.

2. Add it as a custom connector in Claude. Settings → Customize → Connectors → Add custom connector → URL https://<your-hostname>/mcp. Provide the bearer token as the Authorization: Bearer <token> header. Claude will then list the tools above.

Security notes

• The bearer token (MCP_AUTH_TOKEN) is required before the endpoint is ever reachable from the internet. With it empty the server prints a warning and serves unauthenticated — only acceptable bound to localhost.

• The container binds to 127.0.0.1:8787 by default so nothing is exposed except through the tunnel you choose.

• API keys live only in .env (git-ignored, docker-ignored). Rotate them in each app if they ever leak.

• Scope is intentionally read-heavy. Before adding destructive tools (delete series, remove from queue, edit settings), decide whether the convenience is worth the risk on an internet-reachable endpoint.

Files

• server.py — the MCP server and all tools (streamable-HTTP transport + bearer auth)

• arr_client.py — thin async REST client shared by every service

• config.py — builds a client per service from env vars (missing = disabled)

• Dockerfile / docker-compose.yml — container + optional tunnel

• config.example.env — copy to .env