imdb-mcp-server

Instructions

Implementation Reference

• src/imdb_mcp_server/tools.py:13-81 (handler)

  The handler function that implements the search_imdb tool logic. It constructs a search query for the IMDb API, calls the make_imdb_request helper, limits results to the first 5, and returns JSON.

  @mcp.tool()     
  async def search_imdb(
      ctx: Context,
      original_title: Optional[str] = None,
      original_title_autocomplete: Optional[str] = None,
      primary_title: Optional[str] = None,
      primary_title_autocomplete: Optional[str] = None,
      type: Optional[str] = None,
      genre: Optional[str] = None,
      genres: Optional[List[str]] = None,
      is_adult: Optional[bool] = None,
      average_rating_from: Optional[float] = None,
      average_rating_to: Optional[float] = None,
      num_votes_from: Optional[int] = None,
      num_votes_to: Optional[int] = None,
      start_year_from: Optional[int] = None,
      start_year_to: Optional[int] = None,
      countries_of_origin: Optional[List[str]] = None,
      spoken_languages: Optional[List[str]] = None,
      sort_order: Optional[Literal["ASC", "DESC"]] = None,
      sort_field: Optional[Literal["id", "averageRating", "numVotes", "startYear"]] = None,
      ) -> str:
      """Search for movies on IMDb. First 5 results are returned.
      Args:
          original_title: The original title of the movie to search for. Searches the whole word.
          original_title_autocomplete: The autocomplete title of the movie to search for. Searches the partial word.
          primary_title: The primary title of the movie to search for. Searches the whole word.
          primary_title_autocomplete: The autocomplete primary title of the movie to search for. Searches the partial word.
          type: The type of the movie to search for. Get all possible types with get_types().
          genre: The genre of the movie to search for. Get all possible genres with get_genres().
          genres: The genres of the movie to search for. List of Genres. Get all possible genres with get_genres().
          is_adult: Whether to include adult movies in the search results.
          average_rating_from: The minimum average rating of the movie to search for.
          average_rating_to: The maximum average rating of the movie to search for.
          num_votes_from: The minimum number of votes of the movie to search for.
          num_votes_to: The maximum number of votes of the movie to search for.
          start_year_from: The minimum start year of the movie to search for.
          start_year_to: The maximum start year of the movie to search for.
          countries_of_origin: The countries of origin of the movie to search for. In ISO 3166-1 alpha-2 format list of strings. Get all possible countries with get_countries().
          spoken_languages: The spoken languages of the movie to search for. In ISO 639-1 format list of strings. Get all possible languages with get_languages().
          sort_order: The order of the search results. Possible values: "ASC", "DESC".
          sort_field: The field to sort the search results by. Possible values: "id", "averageRating", "numVotes", "startYear".
      Returns:
          JSON object containing the first 5 search results.
      """
      search_url = f"{BASE_URL}/search"
      search_data = await make_imdb_request(search_url, {"originalTitle": original_title,
                                                         "originalTitleAutocomplete": original_title_autocomplete,
                                                         "primaryTitle": primary_title,
                                                         "primaryTitleAutocomplete": primary_title_autocomplete,
                                                         "type": type,
                                                         "genre": genre,
                                                         "genres": genres,
                                                         "isAdult": is_adult,
                                                         "averageRatingFrom": average_rating_from, 
                                                         "averageRatingTo": average_rating_to,
                                                         "numVotesFrom": num_votes_from,
                                                         "numVotesTo": num_votes_to,
                                                         "startYearFrom": start_year_from,
                                                         "startYearTo": start_year_to,
                                                         "countriesOfOrigin": countries_of_origin,
                                                         "spokenLanguages": spoken_languages,
                                                         "sortOrder": sort_order,
                                                         "sortField": sort_field}, ctx)
      if not search_data or not search_data.get("results", []):
          return "Unable to fetch search data for this movie or movie not found."
      
      search_results = search_data.get("results", [])[:5]
      return json.dumps(search_results, indent=4)

• src/imdb_mcp_server/api.py:14-56 (helper)

  Key helper function used by search_imdb to perform the HTTP GET request to the IMDb API endpoint, handling caching, API key retrieval from context or environment, and error handling.

  async def make_imdb_request(url: str, querystring: dict[str, Any], ctx: Optional[Context] = None) -> Optional[Dict[str, Any]]:
      """Make a request to the IMDb API with proper error handling and caching."""
      
      # Check if it's time to clean the cache
      cache_manager.cleanup_if_needed()
      
      # Create a cache key from the URL and querystring
      cache_key = f"{url}_{str(querystring)}"
      
      # Try to get from cache first
      cached_data = cache_manager.cache.get(cache_key)
      if cached_data:
          return cached_data
      
      # Get API key from session config or fallback to environment variable
      api_key = None
      if ctx and hasattr(ctx, 'session_config') and ctx.session_config:
          api_key = ctx.session_config.rapidApiKeyImdb
      
      if not api_key:
          api_key = os.getenv("RAPID_API_KEY_IMDB")
      
      # Not in cache, make the request
      headers = {
          "x-rapidapi-key": api_key,
          "x-rapidapi-host": "imdb236.p.rapidapi.com",
      }
      
      if not api_key:
          raise ValueError("API key not found. Please set the RAPID_API_KEY_IMDB environment variable or provide rapidApiKeyImdb in the request.")
      
      try:
          response = requests.get(url, headers=headers, params=querystring, timeout=30.0)
          response.raise_for_status()
          data = response.json()
          
          # Cache the response
          cache_manager.cache.set(cache_key, data)
              
          return data
      except Exception as e:
          raise ValueError(f"Unable to fetch data from IMDb. Please try again later. Error: {e}")

• src/imdb_mcp_server/main.py:20-23 (registration)

  Location where register_tools is called on the MCP server instance, which in turn defines and registers the search_imdb tool via its @mcp.tool() decorator.

  server = FastMCP("IMDb MCP Server")
  
  # Register all tools with the server
  register_tools(server)

• src/imdb_mcp_server/main.py:11-13 (schema)

  Session configuration schema providing the required rapidApiKeyImdb for the tool to function.

  class ConfigSchema(BaseModel):
      rapidApiKeyImdb: str = Field(..., description="RapidAPI API key for accessing the IMDb API")