Sonarr MCP server
<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;">
Sonarr 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: 49px; height: auto;" alt="Sonarr" src="public/logo.png" />
</h1>
   
</div>
</center>
<hr>
Run Sonarr from Claude.ai and Claude Code. All 234 operations of the v3 API are tools, generated from Sonarr's own OpenAPI document. Not a curated subset: every endpoint Sonarr's web interface can reach, this can reach.
<hr>
## Why not the other options
Measured against `Sonarr.Api.V3/openapi.json`, which has 162 paths and 234 non-HEAD operations:
| Server | Sonarr tools | Coverage |
| --- | --- | --- |
| `davidgibbons/mcp-arr` | 17 | 7 % |
| `niavasha/plex-mcp-server` | 8 | 3 % |
| `bardesss/arr-mcp` | unified verbs across 10 services | partial |
| This one | **234** | **100 %** |
The others hand-write a tool per endpoint they happened to need, so they cover series, queue and calendar and stop there. Nothing else exposes `customformat`, `releaseprofile`, `delayprofile`, `autotagging`, `importlistexclusion`, `manualimport`, `seasonpass`, `remotepathmapping` or `qualitydefinition` at all.
## How it stays complete
`src/sonarr_mcp/tools.py` is generated, not written:
```bash
curl -o openapi.json https://raw.githubusercontent.com/Sonarr/Sonarr/develop/src/Sonarr.Api.V3/openapi.json
python scripts/generate_tools.py openapi.json src/sonarr_mcp/tools.py
```
A test compares every generated call against every operation in the spec, in both directions. An endpoint Sonarr 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_series`, `list_queue` |
| `get_*_by_id` | Read one record | `get_series_by_id` |
| `create_*` | POST | `create_series`, `create_command` |
| `update_*` | PUT | `update_qualityprofile_by_id` |
| `delete_*` | DELETE | `delete_episodefile_by_id` |
234 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
All 69 resource groups: `series`, `episode`, `episodefile`, `seasonpass`, `queue`, `history`, `blocklist`, `calendar`, `wanted`, `command`, `release`, `manualimport`, `rename`, `parse`, `indexer`, `indexerflag`, `downloadclient`, `importlist`, `importlistexclusion`, `qualityprofile`, `qualitydefinition`, `customformat`, `customfilter`, `releaseprofile`, `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/sonarr-mcp.git
cd sonarr-mcp
uv venv && uv pip install -e .
```
```bash
export SONARR_URL=http://127.0.0.1:8989
export SONARR_API_KEY=... # Settings, General, Security
```
### Claude Code
```bash
claude mcp add sonarr -- /path/to/sonarr-mcp/.venv/bin/sonarr-mcp
```
## Writing records
Sonarr 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 |
| --- | --- | --- |
| `sonarr-mcp` | 8520 | The server. No login of its own, never exposed |
| nginx | 8521 | Front door, behind a Cloudflare Tunnel |
| `auth-server.js` | 8522 | 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 'SONARR_URL=...\n' > ~/.config/sonarr-mcp/env
chmod 600 ~/.config/sonarr-mcp/env
```
Copy `systemd/*.service` into `/etc/systemd/system/`, replacing `YOUR_USER` and the `ISSUER` hostname, then:
```bash
sudo systemctl enable --now sonarr-mcp sonarr-mcp-auth
```
Point `nginx/sonarr-mcp.conf` at your own hostname and send the tunnel at `127.0.0.1:8521`.
Environment the server itself reads: `SONARR_URL, SONARR_API_KEY`. The sign-in page carries the Sonarr 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://sonarr-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 .
```
TDQS
Scored across 234 tools
Tools are largely grouped by resource (e.g., list_series, get_series_by_id, update_series_by_id) with clear distinctions. However, there are least ten tools that are effectively static resource fetchers or redundant, such as list_root, get_by_path, and list_system_routes_duplicate, which overlap with generic static resource serving. Additionally, update_episodefile_bulk and update_episodefile_editor have similar purposes (bulk updating episode files) and could be confused, requiring careful reading of descriptions.
The naming follows a consistent verb_noun_pattern (e.g., list_series, create_series, delete_series_by_id, update_series_by_id) with occasional suffix variations like _bulk, _editor, _testall, and _schema. However, the naming is inconsistent in the static resource tools—get_by_path, get_content_by_path, list_root, list_login, list_logout—which don't follow the same resource-action pattern as the API tools. Also, there are odd variations like list_feed_v3_calendar_sonarr_ics, list_wanted_cutoff, and list_wanted_missing that break the pattern, but overall the API tools are consistent.
With 234 tools, the server is massively over-tooled for the intended purpose of a Sonarr (TV show management) MCP. The count is extreme (over 50 tools), and many tools are simple CRUD operations for every resource type, leading to a bloated interface. Typical MCP servers should have 3-15 tools for focused tasks, and 234 tools is far beyond what an agent can effectively navigate.
The tool surface is extremely comprehensive—it covers full CRUD for most resources (series, episodes, episode files, quality profiles, etc.) plus many auxiliary operations like system management, backups, queue management, and manual imports. There are minor gaps like missing explicit get_episode_by_id (but there is list_episode with filters) or missing delete_episode (episodes are managed via series updates), but these are not critical dead ends. The completeness is high for the Sonarr domain, though the sheer volume means some operations are redundant.