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)

Tool	What it does
`search_movie`	Search TMDB for movies matching a title (use before adding).
`add_movie`	Add a movie to the library by TMDB id, optionally searching immediately.
`list_movies`	List library movies, optionally filtered.
`get_movie`	Details for one movie already in the library.
`search_movie_releases`	Ask Radarr to search indexers for a tracked movie.
`delete_movie`	Remove a movie, optionally deleting its files.

Sonarr (TV)

Tool	What it does
`search_series`	Search TVDB for series matching a title (use before adding).
`add_series`	Add a series by TVDB id, optionally starting a search.
`list_series`	List library series, optionally filtered.
`get_series`	Details for one series, including per-season status.
`get_episodes`	List episodes for a series, optionally one season.
`search_season`	Search indexers for every missing episode of one season.
`search_episodes`	Search indexers for specific episode ids.
`delete_series`	Remove a series, optionally deleting its files.

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

Tool	What it does
`get_queue`	What is downloading now, and whether it is actually progressing.
`get_calendar`	Upcoming movie releases / episode air dates in a date window.
`get_history`	Recent grabs, imports, failures and upgrades.
`get_config`	Quality profiles and root folders the instance offers.
`system_status`	Reachability check plus health warnings.

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

Variable	Required	Default	Notes
`RADARR_URL`	with `RADARR_API_KEY`	—	Base URL, no `/api/v3` suffix. Trailing `/` is stripped.
`RADARR_API_KEY`	with `RADARR_URL`	—	Settings → General → Security.
`RADARR_QUALITY_PROFILE`	no	first on instance	Profile name, e.g. `HD-1080p`.
`RADARR_ROOT_FOLDER`	no	first on instance	Path as Radarr sees it, e.g. `/movies`.
`SONARR_URL`	with `SONARR_API_KEY`	—	Base URL, no `/api/v3` suffix.
`SONARR_API_KEY`	with `SONARR_URL`	—	Settings → General → Security.
`SONARR_QUALITY_PROFILE`	no	first on instance	Profile name.
`SONARR_ROOT_FOLDER`	no	first on instance	Path as Sonarr sees it, e.g. `/tv`.
`TRANSPORT`	no	`http`	`http` (streamable HTTP at `/mcp`) or `stdio`.
`HOST`	no	`0.0.0.0`	HTTP transport only.
`PORT`	no	`8000`	HTTP transport only.
`MCP_API_KEY`	no	unset	When set, HTTP clients must send `Authorization: Bearer <key>`. Ignored for stdio.

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.