servarr-mcp

An MCP server exposing Sonarr, Radarr, Prowlarr, and Overseerr to an LLM client. Connect Claude or another MCP-compatible LLM to your media stack and ask it to search for content, manage your library, check download status, and more — all via natural language.

This server reaches Sonarr and Radarr at their /api/v3 endpoints, and Prowlarr at /api/v1. (Note: Sonarr’s published documentation often references “v5” in the URL, but that is the application version, not the API version — use v3.)

Important: This server grants any connected MCP client full read/write access to your media stack, including the ability to permanently delete series, movies, and files on disk. Any LLM you connect can invoke destructive tools. Understand this before enabling it, and configure your MCP client with appropriate safeguards.

Install

Prerequisites: Node.js 20 or later.

From Source

Clone the repository, install dependencies, and build:

git clone https://github.com/jfms7s/servarr-mcp.git
cd servarr-mcp
npm ci
npm run build

Then run the server:

node dist/index.js

The server will start on a stdio interface, expecting MCP protocol messages. Use this command in your MCP client’s configuration (see the Claude Desktop / Claude Code Setup section below).

With Docker

Use the published container image (linux/amd64 and linux/arm64), pinned to a release tag such as v0.1.2, or latest:

docker run --rm -p 3000:3000 \
  -e SERVARR_MCP_TOKEN=a-long-random-secret \
  -e SONARR_URL=http://sonarr:8989 \
  -e SONARR_API_KEY=your-sonarr-api-key \
  -e RADARR_URL=http://radarr:7878 \
  -e RADARR_API_KEY=your-radarr-api-key \
  -e PROWLARR_URL=http://prowlarr:9696 \
  -e PROWLARR_API_KEY=your-prowlarr-api-key \
  -e OVERSEERR_URL=http://overseerr:5055 \
  -e OVERSEERR_API_KEY=your-overseerr-api-key \
  ghcr.io/jfms7s/servarr-mcp:v0.1.2

Note: The image defaults to the HTTP transport (SERVARR_MCP_TRANSPORT=http), which requires SERVARR_MCP_TOKEN — without it the container exits at startup. The URLs must be reachable from inside the container: localhost there is the container itself, not your host. Use the arr containers’ names on a shared Docker network (as above), or their LAN addresses. For many variables, use --env-file:

docker run --rm -p 3000:3000 --env-file .env ghcr.io/jfms7s/servarr-mcp:latest

Where .env contains your configuration lines (one per line: VAR_NAME=value).

Building the Docker Image Locally

If you want to build the image locally:

docker build -t servarr-mcp .
docker run --rm -p 3000:3000 --env-file .env servarr-mcp

Configuration

The server reads configuration from environment variables. Each product is independently optional — you can configure only the ones you use. The server will fail to start only if no products are configured.

Example: Sonarr and Prowlarr only

If you only want to use Sonarr and Prowlarr, set only these:

export SONARR_URL=http://localhost:8989
export SONARR_API_KEY=your-sonarr-key
export PROWLARR_URL=http://localhost:9696
export PROWLARR_API_KEY=your-prowlarr-key
node dist/index.js

The server will register 42 tools (28 Sonarr + 14 Prowlarr) and start normally. Radarr and Overseerr tools will not be available.

Claude Desktop / Claude Code Setup

From Source

Add this to your claude_desktop_config.json or Claude Code MCP server configuration:

{
  "mcpServers": {
    "servarr": {
      "command": "node",
      "args": ["/path/to/servarr-mcp/dist/index.js"],
      "env": {
        "SONARR_URL": "http://localhost:8989",
        "SONARR_API_KEY": "your-sonarr-api-key",
        "RADARR_URL": "http://localhost:7878",
        "RADARR_API_KEY": "your-radarr-api-key",
        "PROWLARR_URL": "http://localhost:9696",
        "PROWLARR_API_KEY": "your-prowlarr-api-key",
        "OVERSEERR_URL": "http://localhost:5055",
        "OVERSEERR_API_KEY": "your-overseerr-api-key"
      }
    }
  }
}

Replace /path/to/servarr-mcp/dist/index.js with the absolute path to the built server in your cloned repository. Replace your-*-api-key with your actual API keys from each application’s Settings → General → API Key.

With Docker

{
  "mcpServers": {
    "servarr": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--add-host=host.docker.internal:host-gateway",
        "--env",
        "SERVARR_MCP_TRANSPORT=stdio",
        "--env",
        "SONARR_URL=http://host.docker.internal:8989",
        "--env",
        "SONARR_API_KEY=your-sonarr-api-key",
        "--env",
        "RADARR_URL=http://host.docker.internal:7878",
        "--env",
        "RADARR_API_KEY=your-radarr-api-key",
        "--env",
        "PROWLARR_URL=http://host.docker.internal:9696",
        "--env",
        "PROWLARR_API_KEY=your-prowlarr-api-key",
        "--env",
        "OVERSEERR_URL=http://host.docker.internal:5055",
        "--env",
        "OVERSEERR_API_KEY=your-overseerr-api-key",
        "ghcr.io/jfms7s/servarr-mcp:latest"
      ]
    }
  }
}

Two things differ from the source setup. SERVARR_MCP_TRANSPORT=stdio is required: the image defaults to HTTP, and without the override it would neither speak stdio nor start at all (HTTP needs a token). And localhost inside the container is the container itself, so the arr apps on your host are reached through host.docker.internal, which the --add-host flag maps to the host on Linux (Docker Desktop provides it already). Replace your-*-api-key with your actual API keys from each application’s Settings → General → API Key.

Remote / HTTP Deployment

For a remote setup (e.g., accessing Sonarr from a separate machine), use the HTTP transport:

From Source

export SERVARR_MCP_TRANSPORT=http
export SERVARR_MCP_PORT=3000
export SERVARR_MCP_TOKEN=your-shared-bearer-token
node dist/index.js

With Docker

docker run --rm -p 3000:3000 \
  -e SERVARR_MCP_TRANSPORT=http \
  -e SERVARR_MCP_PORT=3000 \
  -e SERVARR_MCP_TOKEN=your-shared-bearer-token \
  -e SONARR_URL=http://sonarr:8989 \
  -e SONARR_API_KEY=your-sonarr-api-key \
  ghcr.io/jfms7s/servarr-mcp:latest

The server will listen on the specified port on all interfaces, authenticated with a single bearer token. Control which interfaces can reach it using your container networking, firewall, or reverse proxy configuration.

Two routes are served:

/healthz is deliberately unauthenticated so an orchestrator’s probes can reach it — a probe cannot present a token, and /mcp answers an unauthenticated request with 401, which a probe reads as a failing container. It reports only that this process is still serving. It deliberately does not check your Sonarr, Radarr or Prowlarr instances, so an outage in one of those will not get this container restarted or pulled out of service.

⚠️ Security Warning

The HTTP transport is dangerous. It uses a single shared bearer token for authentication and grants full read/write access to your entire media stack, including the ability to delete series, movies, and files on disk. Never expose this over the open internet. The HTTP interface must be:

1. Behind a VPN
2. Protected by a reverse proxy with additional authentication (e.g., basic auth, OAuth)
3. On a trusted LAN only

A compromised bearer token gives an attacker complete control to delete your library. Use HTTP only in environments you fully control.

Tools

This server exposes 106 tools across the four products.

Sonarr (33 tools)

Radarr (31 tools)

Prowlarr (14 tools)

Overseerr (28 tools)

Organising a library

Several tools exist to audit and correct how a library is filed on disk.

radarr_list_movies and sonarr_list_series filter by rootFolder, genre, titleContains and monitored/file state, and return genres and originalLanguage in the summary. That makes it possible to answer questions like “which animation-genre films are filed under the live-action root” in a single call, instead of one lookup per title. rootFolder matches whole path segments: /media/movies selects that folder only, not /media/movies-animation or /media/movies-anime.

To correct what you find, radarr_update_movie and sonarr_update_series accept a rootFolderPath, and radarr_bulk_edit_movies / sonarr_bulk_edit_series do the same for many items at once. Pass moveFiles: true to relocate the files on disk rather than only changing the record.

Radarr and Sonarr move the files before the bulk editor returns, and a large batch can outlast the MCP client’s request timeout. So the two bulk editors accept at most 10 ids per call when moveFiles is true, and reject a larger batch with an error before anything is sent. Send bigger sets as sequential batches of 10 or fewer, one call at a time. Batches that only change metadata (monitored state, quality profile, tags) are not limited.

radarr_list_unmapped_folders and sonarr_list_unmapped_folders show folders present on disk that the application has no entry for; radarr_import_folder and sonarr_import_folder scan such a folder and import what they find. radarr_get_rename_preview and sonarr_get_rename_preview show the names a rename would produce before you run one, and the find_duplicate_* tools report titles present under more than one root folder.

Routing is decided upstream: overseerr_list_radarr_servers reports the activeDirectory each Radarr server defaults to, which is usually what determines where new requests land. Note that overseerr_update_request changes where a request will be sent — it does not move media that has already been downloaded. Use the Radarr or Sonarr tools for that.

Safety note: deleting files through radarr_delete_movie or sonarr_delete_series requires confirmDeleteFiles: true. Called without it, these tools return a description of what would be lost and delete nothing. The bulk editors deliberately do not expose file deletion at all.

Finding Your API Key

In each application’s web UI:

1. Go to Settings
2. Click General
3. Scroll to the API Key field
4. Copy the entire string

This is a sensitive credential — treat it like a password. Do not commit it to version control or share it.

Development

Prerequisites

• Node.js 20 or later
• npm 10+

Running Tests

npm test

Linting and Type Checking

npm run lint
npm run typecheck

Building

npm run build

This emits compiled JavaScript to dist/index.js.

Running Locally

First build the project, then run it:

npm run build

Then start the server with your configuration:

# Set up environment variables
export SONARR_URL=http://localhost:8989
export SONARR_API_KEY=your-key
# ... other env vars

node dist/index.js