{"id":"05a5f793-604a-4bea-b1c4-c633abe9e106","slug":"orellbuehler-sonarr-mcp","kind":"mcp","name":"sonarr-mcp","summary":"MCP server for Sonarr — lets AI agents like Claude manage your TV library: add series, chase missing episodes, unstick the download queue, tune quality profiles, and diagnose health","owner":"OrellBuehler","repoUrl":"https://github.com/OrellBuehler/sonarr-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-09-05T20:40:24.000Z","addedAt":"2026-10-21T05:06:06.939Z","logoUrl":"https://avatars.githubusercontent.com/u/17276101?u=7ca4a57693674e02d3516b7f554af2dfc841fa1b&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","developer-tools","memory-knowledge"],"tags":["ai-agents","arr","claude","claude-code","llm","media-management","pvr","self-hosted"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T03:06:13.690Z","sample":false,"url":"https://conduits.dev/tools/orellbuehler-sonarr-mcp","language":"TypeScript","transports":["stdio"],"install":{"npm":"@orellbuehler/sonarr-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# sonarr-mcp\n\n[![npm version](https://img.shields.io/npm/v/@orellbuehler/sonarr-mcp)](https://www.npmjs.com/package/@orellbuehler/sonarr-mcp)\n[![CI](https://github.com/OrellBuehler/sonarr-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/OrellBuehler/sonarr-mcp/actions/workflows/ci.yml)\n[![license](https://img.shields.io/npm/l/@orellbuehler/sonarr-mcp)](LICENSE)\n[![node](https://img.shields.io/node/v/@orellbuehler/sonarr-mcp)](package.json)\n\nConnect AI agents to [Sonarr](https://sonarr.tv/). This [Model Context Protocol](https://modelcontextprotocol.io/) server exposes the Sonarr v3 API as 136 tools, so assistants like Claude can manage your TV library — add series, chase missing episodes, unstick the download queue, tune quality profiles, and diagnose health issues.\n\nWorks with any MCP client: Claude Code, Claude Desktop, or your own agent.\n\n## Highlights\n\n- **Library management** — search TVDB, add and remove series, edit them one at a time or in bulk, and monitor or unmonitor whole seasons\n- **Episodes and files** — list episodes, find what is missing, delete or re-tag episode files, preview renames\n- **Downloads** — inspect the queue, remove or blocklist stuck grabs, force imports, and diagnose files needing manual interaction\n- **Interactive search** — query indexers live, see why releases were rejected, and grab the one you want by hand\n- **Quality tuning** — quality profiles and definitions, custom formats, release and delay profiles\n- **Configuration** — indexers, download clients, import lists, notifications, root folders, tags, naming, and media management\n- **Diagnostics** — system status, health checks, disk space, scheduled tasks, command history, and log files\n- **Compact by default** — list tools return summaries instead of Sonarr's very large objects, with `detailed: true` when you need everything\n\nThings you can ask once it's connected:\n\n> \"What's airing this week, and is anything already missing?\"\n>\n> \"Add Severance, 1080p profile, into /tv and search for the whole thing\"\n>\n> \"The queue is stuck — what's wrong and can you fix it?\"\n>\n> \"Find me a release for the season finale that isn't x265\"\n>\n> \"Which of my series are still below their quality cutoff?\"\n\n## Quick start\n\nThe package is published as [`@orellbuehler/sonarr-mcp`](https://www.npmjs.com/package/@orellbuehler/sonarr-mcp) and runs directly with `npx` — no clone or build needed.\n\n1. Get your API key from Sonarr: **Settings > General > Security > API Key**\n2. Register the server with your MCP client. With Claude Code:\n\n```bash\nclaude mcp add sonarr \\\n  --env SONARR_URL=http://your-sonarr-host:8989 \\\n  --env SONARR_API_KEY=your-api-key \\\n  -- npx -y @orellbuehler/sonarr-mcp\n```\n\nOr as JSON config (Claude Desktop and most other MCP clients use the same shape):\n\n```json\n{\n  \"mcpServers\": {\n    \"sonarr\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@orellbuehler/sonarr-mcp\"],\n      \"env\": {\n        \"SONARR_URL\": \"http://your-sonarr-host:8989\",\n        \"SONARR_API_KEY\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\n3. Restart your MCP client. The tools are available immediately.\n\nIf Sonarr runs behind a reverse proxy with a URL base, include it in `SONARR_URL` (e.g. `https://media.example.com/sonarr`).\n\n## Environment variables\n\n| Variable         | Required | Description                                                                                                    |\n| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------- |\n| `SONARR_URL`     | yes      | Base URL of your Sonarr instance, e.g. `http://192.168.1.10:8989`. `http://` is assumed if no scheme is given. |\n| `SONARR_SERVER`  | –        | Accepted as an alias for `SONARR_URL`.                                                                         |\n| `SONARR_API_KEY` | yes      | API key from Settings > General > Security.                                                                    |\n\nThe server speaks stdio only — it is a single-user, single-instance server. It is never asked for your key over the network; the key is read from the environment and sent to Sonarr as the `X-Api-Key` header.\n\n## Available tools\n\n| Category           | Tools                                                                                                                                                                                                                                                                                                                                        |\n| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Series             | `list_series`, `get_series`, `lookup_series`, `add_series`, `update_series`, `delete_series`, `edit_series_bulk`, `delete_series_bulk`, `get_series_folder`, `set_season_monitored`                                                                                                                                                          |\n| Episodes           | `list_episodes`, `get_episode`, `set_episodes_monitored`                                                                                                                                                                                                                                                                                     |\n| Episode files      | `list_episode_files`, `get_episode_file`, `delete_episode_file`, `delete_episode_files`, `update_episode_files`                                                                                                                                                                                                                              |\n| Calendar & wanted  | `get_calendar`, `get_missing_episodes`, `get_cutoff_unmet_episodes`                                                                                                                                                                                                                                                                          |\n| Queue              | `get_queue`, `get_queue_details`, `get_queue_status`, `remove_queue_item`, `remove_queue_items`, `grab_queue_item`, `grab_queue_items`                                                                                                                                                                                                       |\n| History            | `get_history`, `get_history_since`, `get_series_history`, `mark_history_item_failed`                                                                                                                                                                                                                                                         |\n| Blocklist          | `get_blocklist`, `remove_blocklist_item`, `remove_blocklist_items`                                                                                                                                                                                                                                                                           |\n| Search & releases  | `search_releases`, `grab_release`, `get_manual_import_candidates`, `get_rename_preview`, `parse_release_title`                                                                                                                                                                                                                               |\n| Commands           | `run_command`, `list_commands`, `get_command`, `cancel_command`, `refresh_series`, `rescan_series`, `search_series`, `search_season`, `search_episodes`, `list_scheduled_tasks`, `get_scheduled_task`                                                                                                                                        |\n| Quality profiles   | `list_quality_profiles`, `get_quality_profile`, `get_quality_profile_schema`, `create_quality_profile`, `update_quality_profile`, `delete_quality_profile`                                                                                                                                                                                   |\n| Quality & formats  | `list_quality_definitions`, `update_quality_definitions`, `list_custom_formats`, `get_custom_format`, `get_custom_format_schema`, `create_custom_format`, `update_custom_format`, `delete_custom_format`                                                                                                                                     |\n| Release rules      | `list_release_profiles`, `create_release_profile`, `update_release_profile`, `delete_release_profile`, `list_delay_profiles`, `list_languages`                                                                                                                                                                                               |\n| Indexers           | `list_indexers`, `get_indexer`, `get_indexer_schema`, `create_indexer`, `update_indexer`, `delete_indexer`, `test_indexer`                                                                                                                                                                                                                   |\n| Download clients   | `list_download_clients`, `get_download_client`, `get_download_client_schema`, `create_download_client`, `update_download_client`, `delete_download_client`, `test_download_client`                                                                                                                                                           |\n| Import lists       | `list_import_lists`, `get_import_list`, `get_import_list_schema`, `create_import_list`, `update_import_list`, `delete_import_list`, `test_import_list`                                                                                                                                                                                       |\n| Notifications      | `list_notifications`, `get_notification`, `get_notification_schema`, `create_notification`, `update_notification`, `delete_notification`, `test_notification`                                                                                                                                                                                |\n| Root folders       | `list_root_folders`, `get_root_folder`, `add_root_folder`, `delete_root_folder`                                                                                                                                                                                                                                                              |\n| Tags               | `list_tags`, `list_tag_details`, `create_tag`, `update_tag`, `delete_tag`                                                                                                                                                                                                                                                                    |\n| Exclusions & paths | `list_import_list_exclusions`, `add_import_list_exclusion`, `delete_import_list_exclusion`, `list_remote_path_mappings`, `add_remote_path_mapping`, `delete_remote_path_mapping`                                                                                                                                                             |\n| Configuration      | `get_naming_config`, `update_naming_config`, `get_naming_examples`, `get_media_management_config`, `update_media_management_config`, `get_indexer_config`, `update_indexer_config`, `get_download_client_config`, `update_download_client_config`, `get_import_list_config`, `update_import_list_config`, `get_host_config`, `get_ui_config` |\n| System             | `get_system_status`, `get_health`, `get_disk_space`, `get_updates`, `list_logs`, `list_log_files`, `get_log_file`, `list_backups`, `restart_sonarr`                                                                                                                                                                                          |\n\n### Notes\n\n- **List tools return summaries.** `list_series`, `list_episodes`, `get_calendar`, `search_releases` and the wanted lists strip images, overviews and alternate titles so a large library still fits in context. Pass `detailed: true`, or use the matching `get_*` tool, when you need the full object.\n- **Ids.** Sonarr series ids are not TVDB ids. `lookup_series` returns `tvdbId` (what `add_series` takes); everything else takes the Sonarr `id` from `list_series`.\n- **Searching.** `search_series`, `search_season` and `search_episodes` queue Sonarr's own automatic search and return a command id — poll it with `get_command`. `search_releases` instead queries indexers live and returns the candidate releases for you to pick from, which you then send with `grab_release`.\n- **Provider configuration.** Indexers, download clients, import lists and notifications are configured through an implementation-specific `fields` array. Call `get_*_schema` for the template, then pass the whole object to `create_*`; for updates, fetch with `get_*`, change what you need, and send it back. Sonarr masks secrets in responses, so re-sending a fetched object keeps the stored secret.\n- **Destructive operations are explicit.** `delete_series`, `delete_series_bulk` and the queue tools only touch files on disk when you pass `delete_files` / `remove_from_client`, and both default to the safe choice. `restart_sonarr` is included; there is deliberately no shutdown, restore-backup or update-install tool.\n- **Sonarr v4.** The v3 API paths are what Sonarr v4 serves, so this works against both v3 and v4. A handful of endpoints in the published spec (language profiles) exist only on v3 and are not exposed.\n\n## Development\n\n```bash\nnpm install\nnpm run build         # tsc -> dist/\nnpm test              # vitest run\nnpm run lint          # eslint src\nnpm run typecheck     # tsc --noEmit\nnpm run format        # prettier --write .\nnpm run spec:update   # refresh sonarr-openapi.json from the Sonarr repo\n```\n\n`sonarr-openapi.json` is a vendored copy of the [Sonarr v3 OpenAPI spec](https://sonarr.tv/docs/api/) and is the reference for tool parameters — it is not used at runtime.\n\n## License\n\nMIT\n"}