# Sonarr MCP Server

A feature-rich but simple-to-use MCP (Model Context Protocol) server for managing your Sonarr (TV show) instance.

## Features

- **Complete Series Management**: Search, add, edit, and delete TV series
- **Episode Control**: View episodes, search for missing episodes, manage seasons
- **Download Queue**: Monitor downloads, remove stuck items, manage blocklists
- **Calendar & Scheduling**: See upcoming episodes, track releases
- **System Health**: Monitor instance health, check for issues
- **Configuration Management**: Quality profiles, language profiles, root folders, tags

## Installation

```bash
cd mcp-sonarr
npm install
npm run build
```

## Configuration

Set these environment variables:

```bash
export SONARR_URL="http://localhost:8989"        # Your Sonarr URL
export SONARR_API_KEY="your-api-key-here"        # Your API key (Settings > General)
```

Or on Windows:
```powershell
$env:SONARR_URL="http://localhost:8989"
$env:SONARR_API_KEY="your-api-key-here"
```

## MCP Client Configuration

Add to your MCP client config:

```json
{
  "mcpServers": {
    "sonarr": {
      "command": "node",
      "args": ["<YOUR_OPENCODE_DIR>/mcp-sonarr/dist/server.js"],
      "env": {
        "SONARR_URL": "http://localhost:8989",
        "SONARR_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

For development with hot reload:

```json
{
  "mcpServers": {
    "sonarr": {
      "command": "npx",
      "args": [
        "tsx",
        "<YOUR_OPENCODE_DIR>/mcp-sonarr/src/server.ts"
      ],
      "env": {
        "SONARR_URL": "http://localhost:8989",
        "SONARR_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## Available Tools

### Series Management

#### `sonarr_search_series`
Search for TV series by title on TVDB/TMDB. Returns potential matches with metadata.

**Input:**
- `term` (string, required): Search term (e.g., "Breaking Bad", "The Office")

**Output:** List of matching series with tvdbId, title, year, overview, seasons count, etc.

**Note:** Use the `tvdbId` to add a series with `sonarr_add_series`

---

#### `sonarr_get_all_series`
Get all series in your Sonarr library.

**Output:** Complete list of all series with metadata, statistics (episode counts, disk usage), monitoring status.

---

#### `sonarr_get_series`
Get detailed information about a specific series by its Sonarr ID.

**Input:**
- `id` (number, required): Sonarr series ID

**Output:** Full series details including all seasons, episode statistics, images, ratings, and next actions.

---

#### `sonarr_get_series_by_tvdb`
Get series information by TVDB ID.

**Input:**
- `tvdbId` (number, required): TVDB ID (e.g., 81189 for Breaking Bad)

---

#### `sonarr_add_series`
Add a new TV series to your library.

**Input:**
- `tvdbId` (number, required): TVDB ID from search results
- `monitored` (boolean, optional): Whether to monitor the series (default: true)
- `rootFolderPath` (string, optional): Where to store the series (uses default if not specified)
- `qualityProfileId` (number, optional): Quality profile to use (uses default if not specified)
- `languageProfileId` (number, optional): Language profile to use
- `seasonFolder` (boolean, optional): Create season folders (default: true)
- `tags` (number[], optional): Array of tag IDs
- `seasons` (object[], optional): Specify which seasons to monitor

---

#### `sonarr_delete_series`
Delete a series from Sonarr. Optionally delete files from disk.

**⚠️ WARNING:** Deleting files is permanent and cannot be undone!

**Input:**
- `id` (number, required): Series ID to delete
- `deleteFiles` (boolean, optional): Also delete files from disk (default: false)
- `addImportListExclusion` (boolean, optional): Prevent re-import (default: false)

---

#### `sonarr_edit_series`
Edit an existing series (monitoring, quality profile, tags, etc.).

**Input:**
- `series` (object, required): Complete series object with modifications. Must include `id` field.

**Tip:** Get the full series object first with `sonarr_get_series`, modify it, and pass it here.

### Episode Management

#### `sonarr_get_episodes`
Get all episodes for a specific series.

**Input:**
- `seriesId` (number, required): Sonarr series ID
- `seasonNumber` (number, optional): Filter by specific season

**Output:** Episodes list with air dates, file status, monitoring status, and statistics.

---

#### `sonarr_get_episode`
Get detailed information about a specific episode.

**Input:**
- `id` (number, required): Episode ID

---

#### `sonarr_search_episodes`
Search for specific episodes to download. This sends episodes to your download client.

**Input:**
- `episodeIds` (number[], required): Array of episode IDs to search for

---

#### `sonarr_search_season`
Search for all episodes in a specific season.

**Input:**
- `seriesId` (number, required): Sonarr series ID
- `seasonNumber` (number, required): Season number to search

---

#### `sonarr_search_series_command`
Search for all monitored episodes across a series (the "Search All" button).

**Input:**
- `seriesId` (number, required): Sonarr series ID

### Queue & Downloads

#### `sonarr_get_queue`
Get current download queue. Shows active downloads, progress, status, and errors.

**Input:**
- `page` (number, optional): Page number (default: 1)
- `pageSize` (number, optional): Items per page (default: 20)
- `sortKey` (string, optional): Sort field (default: "timeleft")
- `sortDirection` (string, optional): "ascending" or "descending" (default: "ascending")
- `includeUnknownSeriesItems` (boolean, optional): Include unknown items (default: false)

**Output:** Queue items with progress percentage, status, time remaining, and errors.

---

#### `sonarr_remove_from_queue`
Remove an item from the download queue.

**Input:**
- `id` (number, required): Queue item ID
- `blocklist` (boolean, optional): Blocklist release to prevent re-download (default: false)
- `skipRedownload` (boolean, optional): Skip retrying the episode (default: false)
- `changeCategory` (boolean, optional): Change category in download client (default: false)

### Calendar & Missing Episodes

#### `sonarr_get_wanted`
Get wanted/missing episodes that are monitored but don't have files.

**Input:**
- `page` (number, optional): Page number (default: 1)
- `pageSize` (number, optional): Items per page (default: 20)
- `sortKey` (string, optional): Sort field (default: "airDateUtc")
- `sortDirection` (string, optional): "ascending" or "descending" (default: "descending")

**Output:** Missing episodes with series info, ready for searching.

---

#### `sonarr_get_calendar`
Get episodes airing in a date range. Great for seeing what's coming up.

**Input:**
- `start` (string, optional): Start date (YYYY-MM-DD, defaults to today)
- `end` (string, optional): End date (YYYY-MM-DD, defaults to 7 days from start)
- `unmonitored` (boolean, optional): Include unmonitored episodes (default: false)
- `includeSeries` (boolean, optional): Include series data (default: false)
- `includeEpisodeFile` (boolean, optional): Include episode file data (default: false)

**Output:** Episodes grouped by date with air times and availability status.

### System & Configuration

#### `sonarr_get_health`
Get system health status. Shows warnings or errors with your Sonarr instance.

**Output:** Health status with error/warning/notice counts and detailed messages.

---

#### `sonarr_get_system_status`
Get system information (version, OS, database, etc.).

---

#### `sonarr_get_quality_profiles`
Get all quality profiles available for adding series.

---

#### `sonarr_get_language_profiles`
Get all language profiles (if using v3 language profiles).

---

#### `sonarr_get_root_folders`
Get all configured root folders with disk space info.

---

#### `sonarr_get_tags`
Get all tags for organizing series.

### Maintenance

#### `sonarr_refresh_series`
Refresh series information from metadata sources (TVDB). Updates episode info, air dates, etc.

**Input:**
- `seriesId` (number, required): Series ID to refresh

---

#### `sonarr_rescan_series`
Rescan series folder for files. Checks for new, modified, or deleted episode files.

**Input:**
- `seriesId` (number, required): Series ID to rescan

## Common Workflows

### Adding a New Series

1. **Search for the series:**
   ```
   sonarr_search_series with term: "Breaking Bad"
   ```

2. **Add it to your library:**
   ```
   sonarr_add_series with tvdbId from step 1
   ```

3. **Search for episodes:**
   ```
   sonarr_search_series_command with seriesId from step 2
   ```

### Finding and Downloading Missing Episodes

1. **Check wanted episodes:**
   ```
   sonarr_get_wanted
   ```

2. **Search for specific episodes:**
   ```
   sonarr_search_episodes with episodeIds from step 1
   ```

3. **Monitor the queue:**
   ```
   sonarr_get_queue
   ```

### Checking What's Coming Up

```
sonarr_get_calendar
```

Shows episodes airing in the next week by default.

## Error Handling

All tools return clear error messages with context. Common errors:

- **"No series found with TVDB ID X"**: The series doesn't exist on TVDB or the ID is wrong. Search first with `sonarr_search_series`.
- **"No root folder configured"**: Add a root folder in Sonarr settings (System > Root Folders).
- **"No quality profile found"**: Create a quality profile in Sonarr settings (Profiles > Quality).
- **Connection errors**: Check that SONARR_URL and SONARR_API_KEY are set correctly.

## Tips for AI Agents

1. **Always search first** before adding - you need the correct tvdbId
2. **Get configuration first** (root folders, quality profiles) before adding series
3. **Check health regularly** to catch issues early
4. **Use pagination** for large libraries (get_all_series can be big!)
5. **Quote from output** - all tools return structured JSON with helpful notes

## Development

```bash
npm run dev      # Run with tsx (hot reload)
npm run build    # Compile TypeScript
npm run start    # Run compiled version
```

## Requirements

- Node.js 20+
- Sonarr v3 or v4 with API v3
- API key from Sonarr (Settings > General > API Key)