imdb-mcp-server

Instructions

Implementation Reference

• src/imdb_mcp_server/tools.py:86-98 (handler)

  The core handler function for the 'get_imdb_details' tool. It fetches detailed information for a given IMDb ID from the API and returns it as formatted JSON. Registered via @mcp.tool() decorator.

  @mcp.tool()
  async def get_imdb_details(imdb_id: str, ctx: Context) -> str:
      """Get more in depth details about a movie/series from IMDb.
      Args:
          imdbId: The IMDb ID of the movie/series to get details for.
      Returns:
          JSON object containing the movie/series details.
      """
      imdb_details_url = f"{BASE_URL}/{imdb_id}"
      imdb_details_data = await make_imdb_request(imdb_details_url, {}, ctx)
      if not imdb_details_data:
          return "Unable to fetch imdb details data for this movie or movie not found."
      return json.dumps(imdb_details_data, indent=4)

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

  Supporting utility function 'make_imdb_request' called by the handler to perform the actual API request to IMDb, including caching, authentication with RapidAPI key, 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/api.py:11-12 (helper)

  BASE_URL constant used in constructing the API endpoint URL for the tool.

  BASE_URL = "https://imdb236.p.rapidapi.com/api/imdb"

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

  Call to register_tools(server) which defines and registers the get_imdb_details tool among others.

  # Register all tools with the server
  register_tools(server)

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

  Alternative call to register_tools(server) in stdio mode.

  register_tools(server)