# TMDb MCP > The Movie Database (TMDb) MCP Server lets your AI agent search for movies, TV shows, people, and detailed metadata using established industry data. You can find plot overviews, cast lists, trailers, top-rated content, and even filter results by genre or studio in a single chat session. ## Overview - **Category:** knowledge-management - **Price:** Free - **Tags:** movies, tv-shows, metadata, entertainment-data, media-search, cast-information ## Description This MCP Server hooks your AI client up directly to The Movie Database, giving you access to a massive library of movie, TV show, and people metadata. You don't gotta jump between half a dozen sites just to nail down some film facts; your agent handles all that heavy lifting for ya. When you need to find something fast, your client can run `search_multi` to search across movies, TV shows, *and* people using one general query. If you're looking specifically for a title, it runs `search_movies` for films or `search_tv` for series, and both of those let you narrow the results by year when needed. For finding out what's hot right now, you can check what’s trending using the `trending` tool, which pulls real-time popularity data for movies, TV shows, *or* people. You also get lists of currently popular films with `popular_movies`, or a rundown of popular TV series and shows that includes season and episode counts via `popular_tv`. If you want to see what's been critically acclaimed over time, call `top_rated_movies` for the best films ever, or `top_rated_tv` for the most successful television shows. If you know a movie or show by an outside ID—like that IMDb code starting with 'tt'—you don't need to search. Just run `find_by_external_id`, and your agent will grab the corresponding TMDb entry for all other tools. You can also start filtering searches using `discover_movies` when you know specific criteria, letting you narrow down results by genre, minimum rating, production studio, release year, or keywords. Need to dig deep into a film? Use `get_movie` with the TMDb ID to pull all the metadata: the plot overview, budget figures, revenue totals, and total runtime. To map out who played what role, run `get_movie_credits`, which pulls the full cast list (and specifies their characters) plus every single crew member involved in making the film. You can also ask for movie recommendations using `get_movie_recommendations`; it suggests similar films based on a reference title's genre and who starred in it. To get visual assets, use `get_movie_videos` to access official trailers, teasers, and clips associated with the film ID, which provides YouTube links. For classification help, you can call `get_genres` to retrieve the complete list of available genre IDs and names, so you know exactly what filters you're working with. When you need a broad starting point for filtering, you use `discover_movies` with advanced controls that let you set minimum ratings, specify studios, or target specific years. These search functions work together to give you tight control over the results. If your query is general and spans multiple types of media—like searching for 'Star Wars' whether it's a movie or a show—you use `search_multi` to handle the ambiguity in one go. ## Tools ### get_movie_credits Retrieves the complete cast list (with characters) and crew details for a given TMDb movie ID. ### popular_tv Lists currently popular TV series and shows, including season and episode counts. ### find_by_external_id Looks up a movie, TV show, or person by an external ID like IMDb (e.g., 'tt0137523'). ### discover_movies Finds movies using advanced filters for genre, year, rating minimums, studios, and keywords. ### get_genres Retrieves the complete list of available genre IDs and names for filtering in other tools. ### get_movie Gets full metadata—overview, budget, revenue, runtime—for a movie using its specific TMDb ID. ### get_movie_recommendations Suggests similar movies to a reference film, factoring in genre and cast patterns. ### get_movie_videos Accesses official trailers, teasers, and clips for a movie ID, providing YouTube links. ### popular_movies Lists currently popular movies globally or by country code. ### search_movies Searches for movies by title, keyword, or phrase, optionally filtering by release year. ### search_multi Performs a broad search across movies, TV shows, and people using one general query string. ### search_tv Searches for TV series by title or keyword, optionally filtering by first air date year. ### top_rated_movies Lists the highest-rated movies of all time based on user votes. ### top_rated_tv Lists the most critically acclaimed TV shows of all time. ### trending Shows what is currently popular—movies, TV shows, or people—for today or this week. ## Prompt Examples **Prompt:** ``` What movies are trending today? ``` **Response:** ``` Today's trending movies: 1) Dune: Part Three ⭐7.9 (popularity: 2345), 2) The Fantastic Four: First Steps ⭐7.2 (popularity: 1890), 3) Thunderbolts* ⭐7.6 (popularity: 1654), 4) Mission: Impossible — The Final Reckoning ⭐7.4 (popularity: 1432), 5) The Accountant 2 ⭐7.1 (popularity: 1234). Would you like more details or trailers for any of these? ``` **Prompt:** ``` Search for movies directed by Christopher Nolan with rating above 8. ``` **Response:** ``` Found highly-rated Christopher Nolan films: 1) The Dark Knight (2008) ⭐9.0 - When the menace known as the Joker wreaks havoc..., 2) Inception (2010) ⭐8.8 - A thief who steals corporate secrets through dream-sharing technology..., 3) Interstellar (2014) ⭐8.7 - A team of explorers travel through a wormhole in space..., 4) The Prestige (2006) ⭐8.5 - Two stage magicians engage in competitive one-upmanship... Would you like full details or cast for any of these? ``` **Prompt:** ``` Who starred in The Matrix and what other movies have they been in? ``` **Response:** ``` The Matrix (1999) main cast: Keanu Reeves as Neo, Laurence Fishburne as Morpheus, Carrie-Anne Moss as Trinity, Hugo Weaving as Agent Smith. Keanu Reeves' notable films include: John Wick series, Speed, Constantine, John Wick: Chapter 4, The Devil's Advocate, and Point Break. Would you like details on any of these films? ``` ## Capabilities ### Filter movies by criteria Run `discover_movies` to find films based on specific genres, release years, minimum ratings, or production studios. ### Lookup content by external ID Use `find_by_external_id` when you only have an IMDb ID (like 'tt0111161') and need the corresponding TMDb entry for other tools. ### Retrieve full movie details Get comprehensive metadata, including budget, revenue, runtime, and plot summaries, using `get_movie` with a specific movie ID. ### Map cast and crew roles Pull complete lists of actors (with characters) and film staff (directors, producers, etc.) via the `get_movie_credits` tool. ### Suggest similar films Ask for recommendations using `get_movie_recommendations`, which suggests movies based on a provided title's genre and cast. ### Find current popular/trending content Get real-time lists of what's hot right now by calling `popular_movies`, `popular_tv`, or `trending` for movies, shows, or people. ## Use Cases ### Pitching a new project with limited budget The client needs to find comparable films. They ask: "What are some high-rated, low-budget sci-fi thrillers?" The agent first uses `get_genres` to get the IDs for 'Sci-Fi' and 'Thriller', then calls `discover_movies`, setting a minimum vote average (e.g., 7.5) and filtering by genre ID. This returns actionable suggestions they can pitch. ### Writing a retrospective on an actor The client needs to build a bio for an actor like Tom Hanks. They ask: "What are all the movies starring Tom Hanks?" The agent runs `search_multi` using his name, gets a list of relevant movie IDs, and then loops through those IDs calling `get_movie_credits` repeatedly to compile a comprehensive filmography. ### Quickly finding what's currently trending The client asks: "What should we talk about on the show tonight?" The agent runs `trending(mediaType='all', timeWindow='day')`. This immediately provides a list of today's most viewed and talked-about content across movies, TV shows, and people. ### Researching franchise lore The client is researching the Marvel Cinematic Universe. They ask: "Give me all MCU films released by Marvel Studios." The agent uses `discover_movies`, setting the studio ID (Marvel Studios) and filtering for movies, getting a list of specific titles and their release dates. ## Benefits - **Consolidate Data:** Instead of calling multiple search endpoints, use `search_multi`. It returns relevant results—movies, shows, or people—all in one structured payload. This saves several API calls. - **Deep Metadata Access:** Once you find a title using `search_movies`, run `get_movie` to pull the full details: budget, revenue, genre list, and overview. You get the whole file instantly. - **Automate Research:** When writing about film history, use `find_by_external_id`. If your source only has an IMDb ID (like 'tt0111161'), this tool converts it to a working TMDb ID for every other function. - **Build Discovery Funnels:** Start broad with `popular_movies` or `trending`, then narrow down. Use the IDs from these lists in `discover_movies` to filter by specific genres or studios (e.g., 'Marvel Studios'). - **Instant Visual Assets:** Don't manually link trailers. Call `get_movie_videos` and get a list of official YouTube links, including the video type (Teaser, Trailer) and resolution. - **Structured Casting Info:** Never worry about missing roles again. `get_movie_credits` returns two separate arrays: one for actors/characters and one for crew members (directors/writers). It's clean data. ## How It Works The bottom line is, your AI client talks to TMDb through a single endpoint, giving you instant film knowledge without needing separate apps or database connections. 1. Subscribe to the server and input your TMDb API Key. You'll need this key for all calls. 2. Ask your agent a natural language query (e.g., "What are the top-rated 2024 sci-fi films?"). 3. The agent runs necessary tools, like `discover_movies` or `top_rated_movies`, and returns structured data with titles, IDs, and details. ## Frequently Asked Questions **How do I find movies similar to one I already watched and loved?** Use the `get_movie_recommendations` tool with the TMDb ID of the movie you loved. TMDb's algorithm analyzes genre, keywords, cast, crew, and user rating patterns to suggest films you're likely to enjoy. For example, if you loved The Dark Knight (ID: 155), the tool will recommend similar superhero and crime thrillers. You can find the TMDb ID by first using `search_movies` with the title. **Can I filter movies by a specific studio like Warner Bros. or Marvel?** Yes! Use the `discover_movies` tool with the `with_companies` parameter. Studio IDs include: 17 (Warner Bros.), 420 (Marvel Studios), 33 (Universal Pictures), 2 (Walt Disney Pictures), 5 (Columbia Pictures), 12 (New Line Cinema). You can combine with other filters like genre, year, or minimum rating. For example: genre="878" (Sci-Fi), with_companies="420" returns all Marvel sci-fi movies sorted by popularity. **Can I watch trailers directly through this integration?** The `get_movie_videos` tool retrieves all official trailers, teasers, and promotional videos for any movie. Each result includes a YouTube video key. You can watch the trailer by visiting https://www.youtube.com/watch?v={key}. The tool returns videos sorted by type (Trailer, Teaser, Behind the Scenes) with resolution and official status information. **How can I find what movies are trending right now?** Use the `trending` tool with media_type="movie" and time_window="day" for today's trending movies, or time_window="week" for this week's trends. You can also use media_type="all" to see mixed results (movies, TV shows, and people) or media_type="tv" for trending series. Results include popularity scores, vote averages, and poster images. **Can I convert an IMDb ID to a TMDb entry?** Yes! Use the `find_by_external_id` tool with the IMDb ID (e.g., "tt0111161" for The Shawshank Redemption) and external_source="imdb_id". The tool will return the matching TMDb movie, TV show, or person with the TMDb ID, which you can then use with other tools like `get_movie`, `get_movie_credits`, or `get_movie_videos`. This is essential for cross-referencing between IMDb and TMDb databases. **How do I get genre IDs using the `get_genres` tool?** Run `get_genres(type='movie')` first. This returns a comprehensive list of every available movie genre and its unique numerical ID. You must use these returned IDs when calling `discover_movies` to filter results by multiple genres. **What is the purpose of using the `search_multi` tool?** It queries movies, TV shows, and people profiles all in one search. Use this when your query isn't specific to one media type—for example, searching 'Christopher Nolan' returns his films and his person profile simultaneously. **What ID format does the `get_movie` tool require?** It requires the integer TMDb movie ID. This number comes from a prior search or list result, not an external identifier like IMDb's 'tt...' code. Always use `find_by_external_id` if you only have an IMDb ID.