🎬 arrstack-mcp

An MCP server that gives AI assistants configurable access to homelab media and game services.

Works with Claude Desktop, Cursor, VS Code Copilot, OpenClaw, and any other MCP-compatible client.

Demo

Related MCP server: nas-mcp-server

Features

Only configure the services you use — unconfigured services are gracefully skipped.

Choose Your Services

To avoid flooding an MCP client's context with tools it does not need, the advertised tool catalog is configurable:

• ENABLED_SERVICES=auto (default) advertises only services with a configured URL.

• A comma-separated list such as sonarr,radarr,romm advertises exactly that subset.

• ENABLED_SERVICES=all advertises every available tool.

• Run python server.py --list-services to inspect configured/enabled services.

• Run python server.py --setup for an interactive selector that prints the resulting ENABLED_SERVICES line.

Valid service names are sonarr, radarr, lidarr, prowlarr, qbittorrent, rdtclient, sabnzbd, jellyfin, romm, gamevault, and bookshelf. Aliases qbt, rdt, and sab are also accepted.

Quick Start

Option 1: Claude Desktop / Cursor / VS Code (stdio)

1. Install dependencies:

   pip install "mcp[cli]>=1.9.0" httpx

2. Add to your MCP client config (e.g. claude_desktop_config.json):

   {
     "mcpServers": {
       "arrstack": {
         "command": "python",
         "args": ["/path/to/arrstack-mcp/server.py"],
         "env": {
           "SONARR_URL": "http://localhost:8989",
           "SONARR_API_KEY": "your-api-key",
           "RADARR_URL": "http://localhost:7878",
           "RADARR_API_KEY": "your-api-key",
           "QBT_URL": "http://localhost:8080",
           "QBT_USER": "admin",
           "QBT_PASS": "your-password",
           "JELLYFIN_URL": "http://localhost:8096"
         }
       }
     }
   }

3. Restart your MCP client. Done!

Option 2: Docker (HTTP transport)

For remote setups or when running alongside your *arr stack:

git clone https://github.com/ct4nk3r/arrstack-mcp.git
cd arrstack-mcp
cp .env.example .env
# Edit .env with your service URLs and API keys
docker compose up -d

The server runs on port 8000 with Streamable HTTP transport.

Connect to OpenClaw

openclaw mcp set arrstack '{"url":"http://arrstack-mcp:8000/mcp","transport":"streamable-http"}'

Connect to other HTTP MCP clients

Point your client to http://<host>:8000/mcp using Streamable HTTP transport.

Option 3: Docker on the same network as your *arr stack

If your media services run in Docker, add arrstack-mcp to the same network:

services:
  arrstack-mcp:
    build: .
    container_name: arrstack-mcp
    ports:
      - "8000:8000"
    environment:
      - SONARR_URL=http://sonarr:8989
      - SONARR_API_KEY=your-key
      - RADARR_URL=http://radarr:7878
      - RADARR_API_KEY=your-key
      - QBT_URL=http://qbittorrent:8080
      - QBT_USER=admin
      - QBT_PASS=your-password
      - JELLYFIN_URL=http://jellyfin:8096
    networks:
      - your-media-network

Configuration

All configuration is done via environment variables:

Available Tools

Sonarr (TV Shows)

Radarr (Movies)

Lidarr (Music)

Prowlarr (Indexers)

qBittorrent (Downloads)

SABnzbd (Usenet Downloads)

RDTClient (Real-Debrid Downloader)

RDTClient is a Real-Debrid / AllDebrid / Premiumize download manager that exposes a qBittorrent-compatible API, so it slots into Sonarr/Radarr just like qBt.

Jellyfin (Media Server)

RomM (ROM Library)

GameVault (PC Game Library)

Bookshelf (Books — Hardcover-flavored Readarr fork)

Bookshelf is pennydreadful/bookshelf, a fork of Readarr that uses hardcover.app as its metadata provider. It exposes the standard Readarr v1 API, so these tools behave like the Sonarr/Radarr/Lidarr equivalents.

Transport Options

# stdio (default) — for Claude Desktop, Cursor, VS Code
python server.py

# Streamable HTTP — for Docker / remote
python server.py --transport streamable-http --port 8000

# SSE — legacy HTTP transport
python server.py --transport sse --port 8000

Agentic Resource Discovery (ARD)

arrstack-mcp implements the publisher side of Agentic Resource Discovery (spec) — an open standard for publishing and discovering AI capabilities across the web. This lets ARD registries and agents find your server and learn how to connect to it, instead of every client needing a hand-written config.

When running an HTTP transport, the server publishes two documents, generated live from whatever ENABLED_SERVICES advertises:

Both are served with Content-Type: application/json. When ARD_PUBLIC_URL is set (i.e. you've opted into public discovery), they also send Access-Control-Allow-Origin: * so browser-based crawlers can fetch them from any origin; on a private deployment that wildcard CORS header is omitted. Server-side crawlers ignore CORS and work either way.

Identity & trust

The catalog entry's identifier is a domain-anchored urn:air URN — a stable logical name (e.g. urn:air:arrstack.example.com:server:arrstack); it does not need to resolve. A did:web host identity is opt-in: it's only emitted when you set ARD_DID_WEB to a domain whose root you control and where you host a DID document at /.well-known/did.json. It is never inferred from ARD_PUBLIC_URL/ARD_DOMAIN, so the catalog never advertises an identity that can't be verified. This implementation does not include a cryptographic trustManifest (signing / attestations) — that's an optional, enterprise-grade layer of the spec.

Publishing

1. Set ARD_PUBLIC_URL to the URL clients reach this server at, e.g. https://arrstack.example.com. The catalog then advertises an absolute connection endpoint (override the URN namespace with ARD_DOMAIN).

2. Serve it over HTTPS on your public domain (a reverse proxy / Tailscale Funnel / Cloudflare Tunnel in front of port 8000).

3. Check discovery works:

   curl https://arrstack.example.com/.well-known/ai-catalog.json

Startup logs print the discovery URL when ARD is enabled. Set ARD_ENABLED=false to turn the endpoints off.

Static hosting on GitHub Pages (no domain, no public server)

You don't need a custom domain or a publicly exposed MCP server to publish a discoverable catalog — host it as a static file on GitHub Pages, anchored to the github.io domain you already control. This repo ships a workflow (.github/workflows/ard-pages.yml) that regenerates the catalog from server.py on every change and deploys it, so it never goes stale.

Setup (one-time, ~2 minutes):

1. Enable Pages: repo Settings → Pages → Build and deployment → Source: "GitHub Actions".

2. Flip the deploy gate on: repo Settings → Secrets and variables → Actions → Variables, add ARD_PAGES_ENABLED = true. (The deploy job is skipped until you do this, so the workflow stays green beforehand — GitHub's token can't enable Pages for you, so this is an explicit opt-in.)

3. Run it: push to main (or Actions → Publish ARD catalog → Run workflow). The catalog goes live at:

   https://ct4nk3r.github.io/arrstack-mcp/.well-known/ai-catalog.json

4. Verify:

   curl -L https://ct4nk3r.github.io/arrstack-mcp/.well-known/ai-catalog.json

Before you complete steps 1–2, the workflow still runs and stays green: the Build ARD catalog job generates and validates the catalog, and the deploy job is simply skipped.

With no configuration, the publisher identity defaults to your Pages domain — urn:air:ct4nk3r.github.io:server:arrstack. This matches the ARD spec's "solo developer" examples (which use identifiers like urn:air:github.com:alice-dev:...). GitHub Pages serves the file over HTTPS with Content-Type: application/json and Access-Control-Allow-Origin: *, satisfying the ARD hosting requirements, and the manifest embeds the full server card inline so it's self-contained.

Optional repo variables (Settings → Secrets and variables → Actions → Variables) let you override the defaults:

Getting it indexed by registries

Hosting makes the catalog reachable; registries still have to find it. Without a custom domain you have two routes:

• Direct fetch / manual submission (works now). Any agent or registry you give the URL above can fetch and index it immediately — the spec explicitly supports bypassing search and fetching a known catalog directly. Many registries also let you submit a catalog URL for crawling.

• Automatic .well-known discovery (optional, still no purchase). Crawlers that probe https://<domain>/.well-known/ai-catalog.json expect it at a domain root. To get that for free, create a GitHub user site — a repo named ct4nk3r.github.io — and host the same files there, so the catalog sits at https://ct4nk3r.github.io/.well-known/ai-catalog.json (root, not a subpath). Copy .github/workflows/ard-pages.yml and server.py/ard.py into that repo, or just commit the generated ai-catalog.json from the manual command below.

Generating the files manually

To host elsewhere (another repo, S3, a CDN, your own server), generate the documents yourself:

ARD_DOMAIN=ct4nk3r.github.io ARD_EMBED_CARD=true \
  python server.py --print-catalog > ai-catalog.json
ARD_DOMAIN=ct4nk3r.github.io \
  python server.py --print-server-card > mcp-server-card.json

ARD_EMBED_CARD=true makes --print-catalog embed the server card inline so the manifest is self-contained (the default auto only embeds when ARD_PUBLIC_URL is unset). See examples/ for sample output.

Finding Your API Keys

• Sonarr: Settings → General → API Key

• Radarr: Settings → General → API Key

• Lidarr: Settings → General → API Key

• Prowlarr: Settings → General → API Key

• qBittorrent: Settings → Web UI → Authentication

• SABnzbd: Config → General → API Key

• RDTClient: Settings → General → Authentication (or set Authentication: None to allow open access on a trusted network)

• Jellyfin: Dashboard → API Keys → Add

• RomM: User profile → API Tokens, or configure ROMM_USER and ROMM_PASS

• GameVault: Admin panel → API Keys

• Bookshelf: Settings → General → API Key (same as Readarr)

Security

The HTTP/SSE transports listen on 0.0.0.0:8000 by default, and MCP does not provide authentication by itself. Anyone who can reach that port can invoke tools using the configured service credentials.

• Prefer stdio for same-machine clients.

• For remote access, restrict port 8000 to Tailscale or place it behind an authenticated reverse proxy.

• DNS-rebinding protection is enabled. Set MCP_ALLOWED_HOSTS to the exact hostnames or IP addresses clients use, with optional wildcard ports: localhost:*,127.0.0.1:*,arrstack-mcp:*,100.64.0.1:*.

• The Docker image runs as non-root user appuser with UID 1000.

• API keys and request headers are never logged.

License

MIT