<center align="center" style="text-align: center;justify-content:center;">
<div align="center" style="text-align: center;justify-content:center;">
<h1 align="center" style="text-align: center;justify-content:center;">

Radarr MCP server

<img style="justify-content:center;text-align: center;width: 95px; height: auto;" width="793" height="411" alt="image" src="https://github.com/user-attachments/assets/abed1a04-d69b-4ab4-a490-d606064df72d" />
<img style="justify-content:center;text-align: center;width: 152px; height: auto;" alt="Radarr" src="public/logo.png" />

</h1>


![Version](https://img.shields.io/badge/version-1.0.0-blue.svg?style=for-the-badge) ![Python](https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white) ![Radarr](https://img.shields.io/badge/Radarr-FFC230?style=for-the-badge&logo=radarr&logoColor=white) ![Coverage](https://img.shields.io/badge/API_coverage-237%2F237-brightgreen?style=for-the-badge)

</div>
</center>

<hr>

Run Radarr from Claude.ai and Claude Code. All 237 operations of the v3 API are tools, generated from Radarr's own OpenAPI document. Not a curated subset: every endpoint Radarr's web interface can reach, this can reach.

<hr>

> [!WARNING]
> Using this server with a paid AI service costs money. Tool definitions and results are billed as input tokens, and an agent can call tools repeatedly on its own. You are responsible for every charge, so set spending limits with your provider. The author accepts no liability for any costs. See [DISCLAIMER.md](DISCLAIMER.md).

## Why not the other options

Measured against `Radarr.Api.V3/openapi.json`, which has 164 paths and 237 non-HEAD operations:

| Server | Radarr tools | Coverage |
| --- | --- | --- |
| `davidgibbons/mcp-arr` | 18 | 8 % |
| `niavasha/plex-mcp-server` | 8 | 3 % |
| `bardesss/arr-mcp` | unified verbs across 10 services | partial |
| This one | **237** | **100 %** |

The others hand-write a tool per endpoint they happened to need, so they cover movies, queue and calendar and stop there. Nothing else exposes `customformat`, `delayprofile`, `autotagging`, `exclusions`, `alternativetitle`, `extrafile`, `manualimport`, `seasonpass`, `remotepathmapping` or `qualitydefinition` at all.

## How it stays complete

`src/radarr_mcp/tools.py` is generated, not written:

```bash
curl -o openapi.json https://raw.githubusercontent.com/Radarr/Radarr/develop/src/Radarr.Api.V3/openapi.json
python scripts/generate_tools.py openapi.json src/radarr_mcp/tools.py
```

A test compares every generated call against every operation in the spec, in both directions. An endpoint Radarr adds and this misses fails the build; so does a tool pointing at an endpoint the spec does not define.

## Tool names

Verb first, derived from the method and path, so the name says what it does:

| Pattern | Meaning | Example |
| --- | --- | --- |
| `list_*` | Read a collection | `list_movie`, `list_queue` |
| `get_*_by_id` | Read one record | `get_movie_by_id` |
| `create_*` | POST | `create_movie`, `create_command` |
| `update_*` | PUT | `update_qualityprofile_by_id` |
| `delete_*` | DELETE | `delete_moviefile_by_id` |

237 tools is a lot to put in front of a model at once. If your client supports tool filtering, narrow it to the groups you use.

## What is covered

Every resource group: `movie`, `moviefile`, `collection`, `credit`, `queue`, `history`, `blocklist`, `calendar`, `wanted`, `command`, `release`, `manualimport`, `rename`, `parse`, `indexer`, `indexerflag`, `downloadclient`, `importlist`, `exclusions`, `alternativetitle`, `extrafile`, `qualityprofile`, `qualitydefinition`, `customformat`, `customfilter`, `delayprofile`, `autotagging`, `notification`, `metadata`, `tag`, `rootfolder`, `remotepathmapping`, `language`, `localization`, `mediacover`, `filesystem`, `diskspace`, `health`, `log`, `update`, `backup`, `system` and the config endpoints.

## Setup

```bash
git clone https://github.com/rollecode/radarr-mcp.git
cd radarr-mcp
uv venv && uv pip install -e .
```

```bash
export RADARR_URL=http://127.0.0.1:7878
export RADARR_API_KEY=...   # Settings, General, Security
```

### Claude Code

```bash
claude mcp add radarr -- /path/to/radarr-mcp/.venv/bin/radarr-mcp
```

## Writing records

Radarr replaces a record on PUT rather than merging, so read it first, change the fields you want and send the whole object back as `body`. For a new resource, `list_*_schema` returns the shape it expects.

## Hosting it

Running it over HTTP puts it in reach of Claude.ai as a custom connector, and of Claude Code on other machines. Three tiers, the same shape the other servers in this family use:

| Tier | Port | What it does |
| --- | --- | --- |
| `radarr-mcp` | 8530 | The server. No login of its own, never exposed |
| nginx | 8531 | Front door, behind a Cloudflare Tunnel |
| `auth-server.js` | 8532 | OAuth 2.1 sign-in, or a fixed bearer token |

```bash
npm install
node set-password.js 'a password for the sign-in page'
printf 'RADARR_URL=...\n' > ~/.config/radarr-mcp/env
chmod 600 ~/.config/radarr-mcp/env
```

Copy `systemd/*.service` into `/etc/systemd/system/`, replacing `YOUR_USER` and the `ISSUER` hostname, then:

```bash
sudo systemctl enable --now radarr-mcp radarr-mcp-auth
```

Point `nginx/radarr-mcp.conf` at your own hostname and send the tunnel at `127.0.0.1:8531`.

Environment the server itself reads: `RADARR_URL, RADARR_API_KEY`. The sign-in page carries the Radarr mark and accent colour, set through `APP_NAME`, `APP_ACCENT` and `APP_BLURB` in the auth unit.

### Claude.ai

Settings, Connectors, Add custom connector, URL `https://radarr-mcp.your-domain/mcp`, client ID and secret blank. The sign-in page asks for the password set above. Connectors belong to the account, so adding it once covers mobile too.

## Development

```bash
uv pip install -e . pytest ruff
.venv/bin/python -m pytest tests
.venv/bin/ruff check .
```