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")