Sonarr MCP Server
A Model Context Protocol (MCP) server for Sonarr, enabling AI assistants to manage your TV series collection through natural language interactions.
Features
- 🔍 Search Series - Find TV series to add to your collection
- ➕ Add Series - Add TV series with quality profiles, season monitoring, and search options
- 📋 List Series - View your entire TV series library with episode counts
- 📺 Series Details - Get detailed information including episode status and downloads
- ⚙️ Update Series - Change quality profiles, season monitoring, and trigger searches
- 🗑️ Delete Series/Seasons - Remove entire series or specific seasons (with optional file deletion)
- 🔍 Interactive Search - Browse available releases for episodes with quality and seeder info
- 📊 Quality Profiles - View available quality settings
- ⬇️ Download Release - Manually download specific releases for episodes
- 🎯 Season Control - Granular monitoring and management of individual seasons
Installation
From PyPI (Recommended)
pip install sonarr-mcp
From Source
git clone https://github.com/MichaelReubenDev/sonarr-mcp.git
cd sonarr-mcp
uv sync
Usage
Command Line
# Using uvx (if installed from PyPI)
uvx sonarr-mcp --url http://localhost:8989 --api-token YOUR_API_TOKEN
# Using uv run (from source)
uv run sonarr-mcp --url http://localhost:8989 --api-token YOUR_API_TOKEN
# With debug logging
uv run sonarr-mcp --url http://localhost:8989 --api-token YOUR_API_TOKEN --debug
With Claude Desktop
Add this to your Claude Desktop MCP configuration:
{
"mcpServers": {
"sonarr": {
"command": "uvx",
"args": [
"sonarr-mcp",
"--url", "http://localhost:8989",
"--api-token", "YOUR_API_TOKEN"
]
}
}
}
With MCP Inspector
For testing and development:
npx @modelcontextprotocol/inspector uv run sonarr-mcp --url http://localhost:8989 --api-token YOUR_API_TOKEN
Configuration
Required Parameters
--url: Your Sonarr base URL (e.g.,http://localhost:8989)--api-token: Your Sonarr API token (found in Settings → General → Security)
Optional Parameters
--debug: Enable debug logging
Available Tools
| Tool | Description | Parameters |
|---|---|---|
search_series | Search for TV series to add | query (string) |
add_series | Add a TV series to Sonarr | tvdb_id (int), quality_profile_id (int), monitor_type (string, required), root_folder_path (string, default: "/tv"), season_folder (bool, default: true), monitor_seasons (array, optional), search_for_missing_episodes (bool, default: false) |
list_series | List all TV series in library | None |
get_series | Get detailed series information | series_id (int) |
update_series | Update series settings | series_id (int), quality_profile_id (int, optional), monitor_type (string, optional), monitor_seasons (array, optional), start_search (bool, default: false) |
delete_series | Delete a series or specific seasons | series_id (int), delete_seasons (array, optional), delete_files (bool, default: false) |
interactive_search | Browse available releases | series_id (int), season_number (int, optional), episode_number (int, optional) |
download_release | Download a specific release | release_guid (string), series_id (int) |
get_quality_profiles | List available quality profiles | None |
Monitor Types
The monitor_type parameter supports these options:
all- Monitor all episodesfuture- Monitor future episodes onlymissing- Monitor missing episodesexisting- Monitor existing episodesrecent- Monitor recent episodesfirst- Monitor first season onlylatest- Monitor latest season onlynone- Monitor no episodesseason_specific- Monitor specific seasons (requiresmonitor_seasonsarray)
Example Workflows
Adding a TV Series
- Search for series: "Search for Breaking Bad TV series"
- Add series: "Add Breaking Bad with HD-1080p quality, monitor all episodes"
- Add with specific seasons: "Add The Office with monitor_type: 'season_specific' and monitor_seasons: [1, 2, 3]"
- Check status: "Show me details for Breaking Bad"
Managing Your Collection
- List series: "Show me all my TV series"
- Update monitoring: "Change series ID 123 to monitor only seasons 2 and 4"
- Update quality and search: "Change series ID 123 to 4K quality and start searching for missing episodes"
- Browse releases: "Show me available releases for series ID 123 season 2"
Season-Specific Management
- Monitor specific seasons: "Update series ID 123 with monitor_type: 'season_specific', monitor_seasons: [1, 3, 5]"
- Delete specific seasons: "Delete seasons 2 and 4 from series ID 123 including files"
- Search specific episodes: "Show releases for series ID 123 season 3 episode 5"
Finding Downloads
- Get series details: "Show me the status of Game of Thrones"
- Interactive search: "What releases are available for The Walking Dead season 1?"
- Episode search: "Find releases for series ID 456 season 2 episode 10"
Requirements
- Python 3.13+
- Sonarr v3+ with API access
- Network access to your Sonarr instance
Development
# Clone the repository
git clone https://github.com/MichaelReubenDev/sonarr-mcp.git
cd sonarr-mcp
# Install dependencies
uv sync
# Test with the MCP Inspector
task mcp_inspector
# Run with debug logging
uv run sonarr-mcp --url http://localhost:8989 --api-token YOUR_TOKEN --debug
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
- Sonarr - The amazing TV series collection manager
- Model Context Protocol - For enabling AI tool integration
- Anthropic - For Claude and MCP development