add_show_by_tvdb_id
Add a TV show to Sonarr using its TVDB ID. Specify the show title and optionally set a custom root folder for organization.
Instructions
Add a specific TV show to Sonarr using its TVDB ID.
Args: tvdb_id: The TV Database ID for the show title: The title of the show root_folder: Optional root folder path (e.g., "/storage/anime")
Returns: Result of the add operation
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tvdb_id | Yes | ||
| title | Yes | ||
| root_folder | No |
Implementation Reference
- src/arr_assistant_mcp/main.py:420-438 (handler)Handler function decorated with @mcp.tool, which registers the tool and implements the core logic by instantiating MediaServerAPI and calling its add_series_to_sonarr method.@mcp.tool async def add_show_by_tvdb_id(tvdb_id: int, title: str, root_folder: Optional[str] = None) -> AddMediaResponse: """ Add a specific TV show to Sonarr using its TVDB ID. Args: tvdb_id: The TV Database ID for the show title: The title of the show root_folder: Optional root folder path (e.g., "/storage/anime") Returns: Result of the add operation """ if not config: raise ValueError("Server not configured. Please set up Sonarr API key.") api = MediaServerAPI(config) return await api.add_series_to_sonarr(tvdb_id, title, root_folder)
- src/arr_assistant_mcp/main.py:43-47 (schema)Pydantic model defining the output schema for the add_show_by_tvdb_id tool response.class AddMediaResponse(BaseModel): success: bool message: str media_id: Optional[int] = None
- Core helper method in MediaServerAPI class that performs the actual HTTP POST to Sonarr API to add the series using TVDB ID, handling root folder logic and error responses.async def add_series_to_sonarr(self, tvdb_id: int, title: str, root_folder: Optional[str] = None) -> AddMediaResponse: """Add TV series to Sonarr using TVDB ID""" url = f"{self.config.sonarr_url}/api/v3/series" headers = {"X-Api-Key": self.config.sonarr_api_key} payload = { "title": title, "tvdbId": tvdb_id, "qualityProfileId": self.config.quality_profile_id, "monitored": True, "seasonFolder": True, "addOptions": { "searchForMissingEpisodes": True } } # Set root folder (parameter > config > auto-detect) if root_folder: payload["rootFolderPath"] = root_folder logger.info(f"Using specified root folder: {root_folder}") elif self.config.sonarr_root_folder: payload["rootFolderPath"] = self.config.sonarr_root_folder logger.info(f"Using configured root folder: {self.config.sonarr_root_folder}") else: # Auto-detect first available root folder root_folders = await self.get_sonarr_root_folders() if root_folders: payload["rootFolderPath"] = root_folders[0]["path"] logger.info(f"Using auto-detected Sonarr root folder: {root_folders[0]['path']}") else: logger.warning("No Sonarr root folders found - series may fail to add") try: response = await self.client.post(url, json=payload, headers=headers) if response.status_code == 201: result = response.json() return AddMediaResponse( success=True, message=f"Successfully added '{title}' to Sonarr", media_id=result.get("id") ) else: return AddMediaResponse( success=False, message=f"Failed to add series: {response.text}" ) except Exception as e: logger.error(f"Sonarr API error: {e}") return AddMediaResponse( success=False, message=f"Error communicating with Sonarr: {str(e)}" )
- src/arr_assistant_mcp/main.py:420-420 (registration)The @mcp.tool decorator registers the add_show_by_tvdb_id function as an MCP tool.@mcp.tool
- src/arr_assistant_mcp/main.py:80-92 (helper)Helper method to fetch available root folders from Sonarr, used when auto-detecting root folder path.async def get_sonarr_root_folders(self) -> List[Dict[str, Any]]: """Get available root folders from Sonarr""" url = f"{self.config.sonarr_url}/api/v3/rootfolder" headers = {"X-Api-Key": self.config.sonarr_api_key} try: response = await self.client.get(url, headers=headers) response.raise_for_status() return response.json() except Exception as e: logger.error(f"Failed to get Sonarr root folders: {e}") return []