# OMDb API MCP > OMDb API MCP Server. Access movie and TV show data using IMDb IDs, titles, or batch lookups. Pull critical details like Rotten Tomatoes scores, full cast lists, box office figures, and plot synopses directly into your workflow via your AI client. ## Overview - **Category:** data-analytics - **Price:** Free - **Tags:** movie-metadata, film-ratings, entertainment-data, public-api, media-search ## Description Listen up. This isn't some fancy wrapper; it’s a straight connection to Open Movie Database data for your agent. You pull everything—cast lists, box office numbers, plot synopses, Rotten Tomatoes scores—right into your workflow using just the IMDb ID, title, or keywords. Your AI client handles all the heavy lifting. **Finding What You Need: The Search Tools** Need to start from scratch? Use `search` when you've got general keywords and want to find potential movie or series titles; it spits out possible IMDb IDs for you. If you know you're looking only for a flick, run `search_movies` with your keywords and filter by year options. To nail down a TV show, use `search_series`; that function returns paginated lists of show names and years. When you need to track down specific episodes, the dedicated `search_episodes` tool finds them using titles or keywords in paginated batches. **Pinpointing Titles: The Lookup Tools** You got a unique IMDb ID? Use `get_by_imdb_id`. That's your safest bet because it pulls every bit of metadata for any movie or series without getting confused. If you only know the title, you can use `get_by_title`, but be warned: titles often match multiple things, so you might get a few options back. For deep dives, if you have an IMDb ID and need the most complete data set—including a sprawling plot summary—you run `get_full_by_imdb_id`. If you only know the name but still want all the metadata plus a full synopsis, use `get_full_by_title`. Need to compare several titles at once? Just feed multiple IMDb IDs into `get_multiple_by_id`, and it retrieves the metadata for every single film or show simultaneously. You can also get quick plot summaries using `get_short_plot` by simply providing a title name. **Focusing on Specific Details: Episodes and Scores** If you're working with TV, use `get_episode`. This tool lets you pull full metadata for one specific season episode when you already have its unique IMDb ID. To check scores across the board, use `get_ratings` to get all available rating numbers—IMDb, Rotten Tomatoes, and Metacritic—side-by-side in a single result set. **The Workflow Flow** Your agent can execute these functions together. You start by using `search` or `search_movies` to narrow down potential candidates, then use the correct ID getter (`get_by_imdb_id`) for accuracy. Next, you pull all the detailed info with `get_full_by_imdb_id`, grab comparative scores via `get_ratings`, and if it's a show, drill into specific episodes using `get_episode`. This server doesn't just give you names; it gives you the whole damn context—the box office gross, the full cast list, and what critics actually thought. ## Tools ### get_by_imdb_id Use this for the most accurate way to get all details about a movie or series if you know its unique IMDb ID. ### get_by_title Get details for a film or show when you only know the title, but be careful since titles can match multiple things. ### get_episode Retrieve full metadata for one specific TV episode using its unique IMDb ID. ### get_full_by_imdb_id Get the most complete data set, including a deep plot summary, by providing an IMDb ID. ### get_full_by_title Pull all metadata and a full synopsis for a movie or series when you only have its name. ### get_multiple_by_id Compare several titles at once by listing multiple IMDb IDs in one request. ### get_ratings Get all available rating scores (IMDb, Rotten Tomatoes, Metacritic) for a title or series. ### get_short_plot Fetch a quick, brief summary of the plot for any movie or series by its name. ### search Search for general titles (movies/series) using keywords and filters to find potential IMDb IDs. ### search_episodes Find specific TV episodes by title or keyword, returning paginated lists of episode metadata. ### search_movies Search exclusively for movies using keywords and optional year filters. ### search_series Find TV series only, returning paginated lists of show titles and their years. ## Prompt Examples **Prompt:** ``` What are the ratings for The Dark Knight? ``` **Response:** ``` The Dark Knight (2008) ratings: ⭐ IMDb: 9.0/10 (2.8M votes) | 🍅 Rotten Tomatoes: 94% | 📊 Metacritic: 84/100. Rated PG-13. Directed by Christopher Nolan, starring Christian Bale and Heath Ledger. Box Office: $534,858,444. A critically acclaimed superhero film widely considered one of the best of all time. ``` **Prompt:** ``` Search for movies directed by Christopher Nolan with Interstellar in the title. ``` **Response:** ``` Found: Interstellar (2014) — ⭐ 8.7/10 on IMDb. Runtime: 169 min. Genre: Adventure, Drama, Sci-Fi. Cast: Matthew McConaughey, Anne Hathaway, Jessica Chastain. Director: Christopher Nolan. Plot: A team of explorers travel through a wormhole in space in an attempt to ensure humanity's survival as Earth becomes uninhabitable. Box Office: $701,729,206. Production: Paramount Pictures. ``` **Prompt:** ``` Compare the Lord of the Rings trilogy movies: tt0120737, tt0167261, tt0167260 ``` **Response:** ``` LotR trilogy comparison: 1) The Fellowship of the Ring (2001) ⭐ 8.9 — Runtime: 178 min | Box Office: $897.7M 2) The Two Towers (2002) ⭐ 8.8 — Runtime: 179 min | Box Office: $947.9M 3) The Return of the King (2003) ⭐ 9.0 — Runtime: 201 min | Box Office: $1.146B All directed by Peter Jackson. Return of the King won 11 Academy Awards including Best Picture. ``` ## Capabilities ### Retrieve details by unique IMDb ID You use `get_by_imdb_id` when you have a unique identifier and need all available metadata for a movie or series. ### Get full plot synopses The agent calls the appropriate function to pull long-form, complete plot details for any title. ### Compare multiple sources ratings You use `get_ratings` to get IMDb, Rotten Tomatoes, and Metacritic scores side-by-side in a single result. ### Batch process multiple titles Sending a list of IDs via `get_multiple_by_id` retrieves metadata for several films or shows simultaneously. ### Find specific TV episodes Using the dedicated `get_episode` tool allows you to pull deep details about one specific season episode. ## Use Cases ### Comparing the entire MCU phase 4 A content strategist needs to write a comparative piece on Marvel's recent output. Instead of manually looking up each title, they use `get_multiple_by_id` with all the known IMDb IDs. This instantly pulls box office gross, genres, and basic plot summaries for every film in one batch job. ### Fact-checking a TV show's history A fan wants to know exactly who directed Season 3, Episode 5 of 'The Wire.' They first use `search_series` to find the main series ID, then use `get_episode` with that ID. This provides the specific director and writer for that single episode. ### Quickly checking movie ratings You hear a friend mention 'Dune.' You don't want to open IMDb, RT, and Metacritic separately. You run `get_ratings` with the title or ID. Your agent sends back all three scores instantly so you can compare critical reception. ### Finding obscure films A researcher needs to find every movie from 1972 that was directed by a specific person. They first use `search_movies` with the year filter, then process the returned list of IDs through `get_by_imdb_id` to gather all required metadata. ## Benefits - Cross-reference scores across multiple sources: Use `get_ratings` to pull IMDb, Rotten Tomatoes, and Metacritic scores in a single query. You don't have to open three different tabs to compare critical consensus. - Analyze entire franchises at once: Instead of looking up one movie, use `get_multiple_by_id` with a comma-separated list of IDs. This is perfect for comparing the box office performance across an entire trilogy. - Avoid title ambiguity: If you have an ID, always use `get_by_imdb_id`. Because IMDb IDs are unique, this tool guarantees you're pulling data for the correct movie or show, unlike searching by name alone. - Deep dive into TV episodes: The dedicated `get_episode` tool pulls specific metadata—director, writer, air date—for one episode. This is much more precise than just general series searches. - Access detailed financial metrics: Pull box office gross figures and studio information using `get_by_imdb_id`. You get hard data points useful for market analysis. - Targeted searching: Need to find only movies, or only episodes? Use `search_movies`, `search_episodes`, or `search_series` first. They filter results before you even start getting details. ## How It Works The bottom line is you don't have to visit five different websites; your AI client does it all for you in one conversation. 1. Subscribe to this server and input your OMDb API key. 2. Tell your agent what kind of data you need (e.g., 'Compare the box office numbers for three sci-fi movies'). 3. The agent maps your request, runs multiple tools (`get_multiple_by_id` or `get_ratings`), and compiles the final answer. ## Frequently Asked Questions **What's the difference between searching by title vs. using an IMDb ID?** Using an IMDb ID (e.g., `tt0468569`) is the most accurate method because IDs are unique — there's never ambiguity between different films with the same name. Searching by title can return errors if multiple films share the same title (e.g., "King Kong" has multiple versions). If you know the IMDb ID from a link or another source, always prefer `get_by_imdb_id`. Use `get_by_title` when you only know the film name. **Can I get ratings from multiple sources (IMDb, Rotten Tomatoes, Metacritic) at once?** Yes! Use the `get_ratings` tool with either a movie title or IMDb ID. It returns all available ratings from IMDb (out of 10), Rotten Tomatoes (percentage), and Metacritic (out of 100) in a single call. Not all titles have all three ratings — newer or less popular films may only have IMDb data. The tool also returns the IMDb vote count and Metascore as separate fields. **Can I look up details for multiple movies at the same time?** Yes! Use the `get_multiple_by_id` tool with comma-separated IMDb IDs (e.g., `tt0468569,tt1375666,tt0816692` for the Dark Knight trilogy). It fetches details for each ID and returns them combined in one response. If any ID fails, it shows an error for that specific ID while still returning results for the others. This is ideal for franchise comparisons or batch analysis. **What's the difference between short and full plot summaries?** The short plot provides a concise 1-2 paragraph summary — ideal for quick identification or brief descriptions. The full plot offers a much more detailed synopsis with deeper plot points, character arcs, and story resolution. Use short for quick lookups (`get_by_title`, `get_short_plot`) and full when users want comprehensive understanding (`get_full_by_title`, `get_full_by_imdb_id`). **What do I need to provide when using the `get_by_imdb_id` tool?** You must supply a valid IMDb ID string. This unique code is essential because it guarantees that your request points to one specific title, eliminating any guesswork about which movie or show you mean. **Which search tool should I use if I only want to find TV series using `search_series`?** Use `search_series` when your goal is exclusively finding whole television shows. This tool filters out movies and single episodes, giving you the overarching metadata for the entire season or franchise. **If I use `get_by_title`, what happens if multiple items share the same name?** The API may return an error or simply give you the first match it finds. To avoid ambiguity, always try to narrow your search using optional filters for type (movie/series) and year. **What is the necessary workflow when I want details using `get_episode`?** You can't just search by name; you must first use another tool to get the specific IMDb ID for that episode. The `get_episode` function requires this unique identifier to pull accurate details like air date and writer.