sonarr-mcp

Connect AI agents to Sonarr. This Model Context Protocol 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.

Works with any MCP client: Claude Code, Claude Desktop, or your own agent.

Highlights

• Library management — search TVDB, add and remove series, edit them one at a time or in bulk, and monitor or unmonitor whole seasons
• Episodes and files — list episodes, find what is missing, delete or re-tag episode files, preview renames
• Downloads — inspect the queue, remove or blocklist stuck grabs, force imports, and diagnose files needing manual interaction
• Interactive search — query indexers live, see why releases were rejected, and grab the one you want by hand
• Quality tuning — quality profiles and definitions, custom formats, release and delay profiles
• Configuration — indexers, download clients, import lists, notifications, root folders, tags, naming, and media management
• Diagnostics — system status, health checks, disk space, scheduled tasks, command history, and log files
• Compact by default — list tools return summaries instead of Sonarr's very large objects, with detailed: true when you need everything

Things you can ask once it's connected:

"What's airing this week, and is anything already missing?"

"Add Severance, 1080p profile, into /tv and search for the whole thing"

"The queue is stuck — what's wrong and can you fix it?"

"Find me a release for the season finale that isn't x265"

"Which of my series are still below their quality cutoff?"

Quick start

The package is published as @orellbuehler/sonarr-mcp and runs directly with npx — no clone or build needed.

1. Get your API key from Sonarr: Settings > General > Security > API Key
2. Register the server with your MCP client. With Claude Code:

claude mcp add sonarr \
  --env SONARR_URL=http://your-sonarr-host:8989 \
  --env SONARR_API_KEY=your-api-key \
  -- npx -y @orellbuehler/sonarr-mcp

Or as JSON config (Claude Desktop and most other MCP clients use the same shape):

{
  "mcpServers": {
    "sonarr": {
      "command": "npx",
      "args": ["-y", "@orellbuehler/sonarr-mcp"],
      "env": {
        "SONARR_URL": "http://your-sonarr-host:8989",
        "SONARR_API_KEY": "your-api-key"
      }
    }
  }
}

3. Restart your MCP client. The tools are available immediately.

If Sonarr runs behind a reverse proxy with a URL base, include it in SONARR_URL (e.g. https://media.example.com/sonarr).

Environment variables

| Variable | Required | Description | | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------- | | 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. | | SONARR_SERVER | – | Accepted as an alias for SONARR_URL. | | SONARR_API_KEY | yes | API key from Settings > General > Security. |

The 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.

Available tools

| Category | Tools | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | | Episodes | list_episodes, get_episode, set_episodes_monitored | | Episode files | list_episode_files, get_episode_file, delete_episode_file, delete_episode_files, update_episode_files | | Calendar & wanted | get_calendar, get_missing_episodes, get_cutoff_unmet_episodes | | Queue | get_queue, get_queue_details, get_queue_status, remove_queue_item, remove_queue_items, grab_queue_item, grab_queue_items | | History | get_history, get_history_since, get_series_history, mark_history_item_failed | | Blocklist | get_blocklist, remove_blocklist_item, remove_blocklist_items | | Search & releases | search_releases, grab_release, get_manual_import_candidates, get_rename_preview, parse_release_title | | 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 | | Quality profiles | list_quality_profiles, get_quality_profile, get_quality_profile_schema, create_quality_profile, update_quality_profile, delete_quality_profile | | 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 | | Release rules | list_release_profiles, create_release_profile, update_release_profile, delete_release_profile, list_delay_profiles, list_languages | | Indexers | list_indexers, get_indexer, get_indexer_schema, create_indexer, update_indexer, delete_indexer, test_indexer | | Download clients | list_download_clients, get_download_client, get_download_client_schema, create_download_client, update_download_client, delete_download_client, test_download_client | | Import lists | list_import_lists, get_import_list, get_import_list_schema, create_import_list, update_import_list, delete_import_list, test_import_list | | Notifications | list_notifications, get_notification, get_notification_schema, create_notification, update_notification, delete_notification, test_notification | | Root folders | list_root_folders, get_root_folder, add_root_folder, delete_root_folder | | Tags | list_tags, list_tag_details, create_tag, update_tag, delete_tag | | 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 | | 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 | | System | get_system_status, get_health, get_disk_space, get_updates, list_logs, list_log_files, get_log_file, list_backups, restart_sonarr |

Notes

• 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.
• 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.
• 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.
• 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.
• 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.
• 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.

Development

npm install
npm run build         # tsc -> dist/
npm test              # vitest run
npm run lint          # eslint src
npm run typecheck     # tsc --noEmit
npm run format        # prettier --write .
npm run spec:update   # refresh sonarr-openapi.json from the Sonarr repo

sonarr-openapi.json is a vendored copy of the Sonarr v3 OpenAPI spec and is the reference for tool parameters — it is not used at runtime.

License

MIT