add_movie_by_id

Instructions

Implementation Reference

• src/arr_assistant_mcp/main.py:367-385 (handler)

  The tool handler function 'add_movie_by_id' decorated with @mcp.tool. Accepts tmdb_id (int) and optional root_folder, then delegates to api.add_movie_to_radarr().

  async def add_movie_by_id(tmdb_id: int, root_folder: str | None = None) -> AddMediaResponse:
      """
      Add a specific movie to Radarr using its TMDb ID.
      
      Args:
          tmdb_id: The Movie Database ID for the movie
          root_folder: Optional root folder path (e.g., "/storage/movies")
      
      Returns:
          Result of the add operation
      """
      if not config:
          raise ValueError("Server not configured. Please set up Radarr API key.")
      
      # Use TMDb ID as title placeholder - Radarr will fetch the real title
      title = f"Movie (TMDb ID: {tmdb_id})"
  
      async with MediaServerAPI(config) as api:
          return await api.add_movie_to_radarr(tmdb_id, title, root_folder)

• src/arr_assistant_mcp/main.py:46-49 (schema)

  AddMediaResponse schema (BaseModel) used as the return type of add_movie_by_id, with success, message, and optional media_id fields.

  class AddMediaResponse(BaseModel):
      success: bool
      message: str
      media_id: int | None = None

• src/arr_assistant_mcp/main.py:366-366 (registration)

  Tool registration via the @mcp.tool decorator on line 366, which registers 'add_movie_by_id' with FastMCP.

  @mcp.tool

• src/arr_assistant_mcp/main.py:132-192 (helper)

  The helper method 'add_movie_to_radarr' on MediaServerAPI class that builds the Radarr API payload, handles root folder logic (parameter > config > auto-detect), posts to Radarr, and returns AddMediaResponse.

  async def add_movie_to_radarr(
      self,
      tmdb_id: int,
      title: str,
      root_folder: str | None = None,
  ) -> AddMediaResponse:
      """Add movie to Radarr"""
      url = f"{self.config.radarr_url}/api/v3/movie"
      headers = {"X-Api-Key": self.config.radarr_api_key}
  
      # Use provided title - Radarr will fetch additional details
      if not title:
          title = f"Movie (TMDb ID: {tmdb_id})"
  
      payload = {
          "title": title,
          "tmdbId": tmdb_id,
          "qualityProfileId": self.config.quality_profile_id,
          "monitored": True,
          "minimumAvailability": "announced",
          "addOptions": {
              "searchForMovie": 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.radarr_root_folder:
          payload["rootFolderPath"] = self.config.radarr_root_folder
          logger.info(f"Using configured root folder: {self.config.radarr_root_folder}")
      else:
          # Auto-detect first available root folder
          root_folders = await self.get_radarr_root_folders()
          if root_folders:
              payload["rootFolderPath"] = root_folders[0]["path"]
              logger.info(f"Using auto-detected Radarr root folder: {root_folders[0]['path']}")
          else:
              logger.warning("No Radarr root folders found - movie 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 Radarr",
                  media_id=result.get("id")
              )
          else:
              return AddMediaResponse(
                  success=False,
                  message=f"Failed to add movie: {response.text}"
              )
      except Exception as e:
          logger.error(f"Radarr API error: {e}")
          return AddMediaResponse(
              success=False,
              message=f"Error communicating with Radarr: {str(e)}"
          )

• src/arr_assistant_mcp/main.py:75-86 (helper)

  Helper method 'get_radarr_root_folders' used internally by add_movie_to_radarr for auto-detecting the Radarr root folder when none is explicitly provided.

  async def get_radarr_root_folders(self) -> list[dict[str, Any]]:
      """Get available root folders from Radarr"""
      url = f"{self.config.radarr_url}/api/v3/rootfolder"
      headers = {"X-Api-Key": self.config.radarr_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 Radarr root folders: {e}")
          return []