sonarr-radarr-mcp

One MCP server that exposes both Sonarr (TV) and Radarr (movies) to an AI assistant, built with FastMCP. Look up a title, add it with your configured quality profile and root folder, kick off an indexer search, and ask what the download queue is doing — in plain language.

Both services are optional. Each is enabled only when both its URL and its API key are set; configuring exactly one of a pair is an error and the server refuses to start. At least one service must be configured.

Tools

Radarr (movies)

Sonarr (TV)

Both (take a service argument: "radarr" or "sonarr")

Related MCP server: MCP *arr Server

Where to find your API keys

In each app: Settings → General → Security → API Key. Radarr and Sonarr have separate keys.

Quick start

a) Docker Compose (homelab)

cp .env.example .env   # fill in the URLs and API keys
docker compose up -d

The server listens on http://<host>:8000/mcp.

If your *arr apps run in Docker too, put this container on their network and address them by container name (http://radarr:7878) — see the comments in docker-compose.yml. Otherwise use the host's LAN IP; localhost inside the container means the container.

Set MCP_API_KEY in .env before exposing the port beyond a trusted network — without it the endpoint is unauthenticated, and these tools can delete media.

b) Connect Claude Code (HTTP)

claude mcp add --transport http sonarr-radarr http://HOST:8000/mcp

With MCP_API_KEY set:

claude mcp add --transport http sonarr-radarr http://HOST:8000/mcp \
  --header "Authorization: Bearer YOUR_MCP_API_KEY"

c) Local stdio (Claude Desktop)

Runs the server as a child process — no port, no bearer token needed.

{
  "mcpServers": {
    "sonarr-radarr": {
      "command": "uv",
      "args": [
        "run",
        "--no-editable",
        "--directory", "/absolute/path/to/sonarr_radarr_mcp",
        "sonarr-radarr-mcp"
      ],
      "env": {
        "TRANSPORT": "stdio",
        "RADARR_URL": "http://192.168.1.10:7878",
        "RADARR_API_KEY": "...",
        "SONARR_URL": "http://192.168.1.10:8989",
        "SONARR_API_KEY": "..."
      }
    }
  }
}

TRANSPORT=stdio is required here — the default is http. The env block is also required: the server does not read .env itself. For a manual local run, export it first:

set -a; . ./.env; set +a
uv run --no-editable sonarr-radarr-mcp

Configuration

Quality profiles and root folders are configured by name/path, not id — ids differ between instances. Names are resolved against the live instance at call time.

Example prompts

• "Download the film Dune Part Three"

• "Is my download finished?"

• "Add Severance and start searching for season 2"

• "What's airing this week?"

• "Which movies in my library are still missing files?"

Development

uv sync          # install, including dev dependencies
uv run pytest    # 105 tests

Tests are fully offline — HTTP is mocked with respx, so no live Sonarr or Radarr instance is needed.

CI/CD

Every push runs the test suite; pushes to main additionally build and publish ghcr.io/dannyj/sonarr-radarr-mcp:latest (see .github/workflows/ci.yml). The Docker host runs a systemd timer (deploy/sonarr-radarr-mcp-deploy.timer, every 10 minutes) that pulls the image and restarts the stack only when the digest changed, then verifies the MCP endpoint answers before declaring success (deploy/pull-and-deploy.sh). The host pulls rather than CI pushing, so no inbound access or host credentials live in GitHub. One-time host setup:

git clone https://github.com/dannyj/sonarr-radarr-mcp.git ~/Documents/repos/sonarr-radarr-mcp
cd ~/Documents/repos/sonarr-radarr-mcp && cp .env.example .env  # fill in URLs + keys
sudo cp deploy/sonarr-radarr-mcp-deploy.{service,timer} /etc/systemd/system/
sudo systemctl daemon-reload && sudo systemctl enable --now sonarr-radarr-mcp-deploy.timer

macOS gotcha: if uv run sonarr-radarr-mcp fails with ModuleNotFoundError: No module named 'sonarr_radarr_mcp' despite a clean uv sync, the repo is in an iCloud-synced folder (e.g. ~/Documents): iCloud re-marks the editable-install .pth file hidden+dataless, and CPython silently skips hidden .pth files. chflags nohidden does not stick — iCloud re-applies the flag within a minute. Run with uv run --no-editable sonarr-radarr-mcp instead (real files, no .pth), as all examples above do. pytest is immune (pythonpath = ["src"] in pyproject.toml), and so is the Docker image.