servarr-mcp

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 and search whichever *arr apps you're running.

Apps are optional: configure only the ones you actually run, and only those tools register.

Tools

Sonarr (TV)

Radarr (movies)

Lidarr (music)

Readarr (books)

Prowlarr (indexer manager)

Configuration

Each app uses two environment variables. Set both for an app to enable its tools; leave them unset to skip the app entirely.

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-mcp

Published 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:latest

Run 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 up

The MCP endpoint will be at http://<host>:${HOST_PORT}/mcp.

Deploy via Portainer (Stack from Git)

1. In Portainer, Stacks → Add Stack → Repository.
2. Repository URL: https://github.com/CarlDog/servarr-mcp
3. Compose path: docker-compose.yml
4. Environment variables: set whichever <APP>_URL/<APP>_API_KEY pairs apply, plus optionally HOST_PORT.
5. 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 dev

Security

• 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-commit runs gitleaks on every commit. Activate it once per clone: git config core.hooksPath .githooks.