marcosisocram/sonarr-mcp repository overview

⁠Standalone Sonarr MCP (Go)

An independently deployable MCP (Model Context Protocol) server for Sonarr, written in Go. It exposes one MCP server over Streamable HTTP at /mcp/sonarr and a health endpoint at /health, and talks to Sonarr API v3 (validated against Sonarr 4.0.20.3014-ls329).

⁠Quick start

docker run -d --name sonarr-mcp \
  --read-only --cap-drop ALL --security-opt no-new-privileges:true \
  -e SONARR_URL=http://your-sonarr:8989 \
  -e SONARR_API_KEY='your-sonarr-api-key' \
  -e SONARR_LISTEN_ADDR=0.0.0.0:8080 \
  -p 127.0.0.1:8090:8080 \
  marcosisocram/sonarr-mcp:latest

• MCP endpoint: http://127.0.0.1:8090/mcp/sonarr
• Health: http://127.0.0.1:8090/health

The container runs as a non-root user with no shell, on a distroless base, and declares HEALTHCHECK CMD ["/sonarr-mcp", "--healthcheck"] — the same command a Kubernetes livenessProbe/readinessProbe should use.

⁠Configuration

Never pass upstream URLs through tool arguments — the base URL is trusted configuration only. TLS verification for upstream HTTPS is always enabled, and redirects are never followed so the API key cannot be replayed to another origin.

⁠Tools

Read tools: sonarr_list_series (with monitored filter and limit/offset), sonarr_get_series (with per-season monitoring flags), sonarr_lookup_series, sonarr_list_quality_profiles, sonarr_list_root_folders, sonarr_list_episodes (scoped to one series, with optional season/monitored/has_file filters), sonarr_get_episode, sonarr_get_queue, sonarr_get_history, and sonarr_get_command.

Write tools: sonarr_add_series, sonarr_set_series_monitored, sonarr_set_episode_monitored, sonarr_search_series, sonarr_search_season, and sonarr_search_episodes.

A typical flow is sonarr_lookup_series → sonarr_list_quality_profiles + sonarr_list_root_folders → sonarr_add_series → sonarr_search_series (or sonarr_search_season / sonarr_search_episodes) → sonarr_get_command.

sonarr_add_series requires tvdb_id, quality_profile_id, and root_folder_path; there are no silent defaults for those. It never starts a release search and returns already_exists without writing when the TVDB ID is already in the library. The sonarr_search_* tools ask Sonarr to search indexers for one explicit target and can start downloads; each returns a command ID that sonarr_get_command tracks.

Errors report the operation and HTTP status only — never the API key or the upstream response body. Removing series or files, manual import, config/indexer/download-client editing, backups, and generic administrative commands are not part of this integration.

⁠Security notes

The server provides no inbound authentication. Expose the port only on a trusted network or behind a TLS/access-control proxy. Container hardening shown above (--read-only, cap-drop ALL, no-new-privileges) is recommended for all deployments.

⁠Related images

• marcosisocram/qbittorrent-mcp — qBittorrent
• marcosisocram/radarr-mcp — Radarr (movies)
• marcosisocram/sonarr-mcp — Sonarr (TV series, this image)

⁠Spec and source

https://github.com/marcosisocram/arr-mcp⁠