# TMDB MCP > TMDB (The Movie Database) MCP Server gives your AI agent direct access to massive movie, TV show, and actor metadata. Instead of searching through web pages or using multiple APIs, you query a single source for details like cast lists, genre filters, release dates, and regional certifications. It's the quickest way to build scripts that need reliable film knowledge. Your agent can run complex searches—like finding top-rated horror movies from a specific year—and get structured data back instantly. ## Overview - **Category:** knowledge-management - **Price:** Free - **Tags:** movies, tv-shows, entertainment, film-database, media-metadata ## Description Yo, check it. This ain't your average web search thing. You connect your AI client to **The Movie Database (TMDB)** server, and you get direct piping access to massive film metadata. Forget scraping web pages or juggling a dozen different APIs just to figure out what movie or show was good. You query one spot for everything: cast lists, genre rules, release dates, and regional ratings. *** ### Getting Set Up First off, you gotta get authenticated. Use `create_guest_session` if you're just testing out basic interaction with the server. If your script needs to run complex stuff, generate a fresh, time-limited access credential using `create_request_token`. Before writing any code, pull system details—you can check the API configuration settings with `get_configuration`, or grab specific account data associated with your credentials via `get_account_details`. These tools let you nail down exactly how and where your agent's calls are going to land. *** ### Searching for Content You got two ways to find something. If you know what you want, use `search_movies` to run a basic text query across the whole movie title database. For anything more complicated—like 'show me top-rated horror films from 1985'—you gotta hit up `discover_movies`. This tool lets you filter content using advanced criteria like genre, rating thresholds, or specific release years. *** ### Deep Dive: Movies and Films Once you find a title, you need the goods. Use `get_movie_details` to pull every piece of metadata available for that single film; that includes the full plot summary, runtime data, director name, and cast breakdown. If you just need to know if a movie is legal in your area or what it's rated for, check the official regional content ratings with `get_movie_certifications`. You can’t get all this info from one place, so these tools keep everything structured. *** ### Tracking TV Series and Episodes The process changes when you deal with a whole show. Start by getting comprehensive metadata for the entire series using `get_tv_details`; that pulls in genre data and creator info right away. Next, if you're working on seasonal content, pull the season details—you can use `get_tv_season_details` to get the episode count and run dates for a specific year of the show. For granular detail, grab a single TV episode’s summary, air date, and cast list with `get_tv_episode_details`. And remember, you gotta check official regional content ratings for the whole series using `get_tv_certifications`. *** ### Researching People Need to track down an actor or a director? Use `get_person_details`. This tool retrieves the person's full biography and, more importantly, provides their complete work history—the filmography. Your agent gets a structured list of every movie and show they were involved in, making cast research simple. *** By combining these tools—from finding initial titles with `discover_movies` to tracking down specific episode summaries using `get_tv_episode_details`, or compiling an actor's entire career via `get_person_details`—your script gets reliable, structured data instantly. You don't mess around; you just get the facts. ## Tools ### get_account_details Retrieves specific account-level data associated with your TMDB credentials. ### get_configuration Pulls system and API configuration settings for the TMDB service. ### discover_movies Searches and filters the database to find movies based on specified criteria like genre or year. ### create_guest_session Establishes a temporary, unauthenticated session to start basic interactions with the server. ### get_movie_certifications Checks and retrieves official regional content ratings and certifications for a specific movie. ### get_movie_details Fetches all available metadata for one specific film, including plot, cast, and runtime. ### get_person_details Retrieves detailed biographies and complete work histories (filmography) for any person in the database. ### create_request_token Generates a fresh, time-limited access token needed for authenticated requests across the system. ### search_movies Performs a basic text search across the movie database to find titles matching specific keywords. ### get_tv_certifications Checks and retrieves official regional content ratings and certifications for a TV show series. ### get_tv_details Gets comprehensive metadata about an entire television series, including genre and creator information. ### get_tv_episode_details Fetches all details—summary, air date, cast—for a single TV episode within a season. ### get_tv_season_details Provides metadata for an entire season of a TV show, including the episode count and run dates. ## Prompt Examples **Prompt:** ``` Search for the movie 'Inception'. ``` **Response:** ``` I found 'Inception' (1999) with ID 27205. It's a sci-fi masterpiece directed by Christopher Nolan. Would you like to see the full details or the cast list? ``` **Prompt:** ``` Discover top-rated horror movies from 2023. ``` **Response:** ``` I've filtered the database for 2023 horror movies. Notable titles include 'Talk to Me' and 'When Evil Lurks'. Would you like the specific details for any of these? ``` **Prompt:** ``` Get the details for season 1 of the TV show with ID 1399. ``` **Response:** ``` Fetching details for 'Game of Thrones' (ID: 1399) Season 1. It consists of 10 episodes, starting with 'Winter Is Coming'. Should I provide the summary for the first episode? ``` ## Capabilities ### Discover content by filter Find movies and TV shows using advanced filters like genre, rating, or release date via the `discover_movies` tool. ### Retrieve core movie metadata Get detailed information for a single film—plot summary, runtime, director, etc.—using `get_movie_details`. ### Track TV series and seasons Pull data on an entire show (`get_tv_details`), specific season details (`get_tv_season_details`), or individual episodes (`get_tv_episode_details`). ### Lookup people's filmographies Get a person’s bio and list all the films and shows they were involved in using `get_person_details`. ### Check content ratings Access official regional certifications for movies or TV series to understand content limitations using dedicated tools. ## Use Cases ### Building a streaming guide for new users A content team needs to generate a 'Top 10' list. They start by running `discover_movies` with filters for 'Comedy' and '2023'. Then, they iterate through the results, calling `get_movie_details` on each title to grab the runtime and main cast. The agent compiles this structured data into a markdown file ready for publication. ### Checking for licensing conflicts A legal team is building an ad campaign around a TV show. They first use `get_tv_details` to confirm the series ID, then call `get_tv_certifications`. This confirms the content rating and regional limits before any creative work starts, preventing costly re-edits. ### Cross-referencing talent on a project A user wants to write an article about a director. They use `get_person_details` for the director's bio. Then, they take one of the films listed in the bio and run `get_movie_details` again to get the original plot summary and cast list, ensuring all facts are current. ### Finding a specific episode recap A user remembers a key scene from 'Game of Thrones' Season 4. They use `get_tv_details` to find the show ID, then call `get_tv_season_details` for season 4, and finally specify the episode number to run `get_tv_episode_details`. The agent returns the full summary text instantly. ## Benefits - Get deep, structured data immediately. Instead of scraping a webpage for cast names, use `get_movie_details` to pull the full list and roles into your script. - Manage complex content research easily. You can filter by genre *and* year using `discover_movies`, giving you reliable lists that simple web searches miss. - Keep track of TV shows properly. Use the dedicated tools—`get_tv_details` to find the series, then `get_tv_season_details` for season specifics, and finally `get_tv_episode_details` for the episode summary. - Validate content legality. Before publishing anything, use `get_movie_certifications` or `get_tv_certifications` to check regional rating requirements directly through your agent. - Research people's work history in bulk. If you need to know every movie an actor was in, running `get_person_details` saves hours of cross-referencing. ## How It Works The bottom line is: it gives your AI client a dedicated, reliable pipeline to query global movie and TV knowledge without leaving your terminal or IDE. 1. First, subscribe to the server and provide your TMDB API Read Access Token (v4) within the client settings. 2. Next, prompt your AI agent with a request—for example, 'Find all sci-fi movies released in 2023.' 3. The agent executes the necessary tools (`discover_movies` or `search_movies`) and returns structured JSON data containing the film's metadata. ## Frequently Asked Questions **How do I search for a movie title using `search_movies`?** Just ask your agent to 'Search for the film Titanic.' The tool runs a basic text query and returns matching titles. It's fast, but remember that for detailed filtering (like genre or year), you should use `discover_movies` instead. **Which tool do I use to get actor bios? Is it `get_person_details`?** Yes, that’s right. Use `get_person_details` and provide the person's ID or name. It gives you their full bio and a complete list of every film they worked on. **Can I get details for a TV show season using `get_tv_season_details`?** Absolutely. First, use `get_tv_details` to find the main series ID. Then, you pass that and the desired season number into `get_tv_season_details`. This tells you exactly how many episodes are in that season. **What's the difference between `get_movie_details` and `discover_movies`?** `search_movies` finds titles by keyword. `discover_movies` lets you filter results using criteria (genre, rating) to find a whole group of content, giving you more control over your search. **I need certifications—do I use `get_movie_certifications` or something else?** You must use the dedicated tool: `get_movie_certifications`. It pulls official rating data specific to movies. If it's a TV show, you have to run `get_tv_certifications`. **How do I handle authentication or rate limits when using `create_request_token`?** Your AI client manages token refreshing automatically. When you initiate a query, the agent first handles session setup and ensures your request token is active before calling any data tools. If the token expires or hits a limit, the system prompts you to refresh credentials. **What parameters can I pass to `discover_movies` beyond just genre?** You can filter by release date range, minimum user rating, and specific cast members. Simply tell your agent what criteria you need—like 'all 80s sci-fi films rated above 7'—and the tool handles the complex parameter mapping. **Beyond a summary, what metadata does `get_tv_episode_details` provide?** It provides deep specifics including air date, runtime, writer credits, and director names. This level of granularity lets you build out comprehensive research reports for a series' production history. **Can I filter movies by specific genres and ratings?** Yes! Use the `discover_movies` tool. You can provide genre IDs in `with_genres` and use other filters like `sort_by` to find highly-rated content. **How do I get information about a specific actor?** Use the `get_person_details` tool with the person's unique ID. It will return their biography, place of birth, and other metadata. **Can I see the episodes of a specific TV season?** Absolutely. Use `get_tv_season_details` by providing the `series_id` and the `season_number`. It will list all episodes in that season.