TMDB MCP Server
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| TMDB_REGION | No | Region for localization (e.g., US, RU) (optional) | |
| OMDB_API_KEY | No | OMDb API key for ratings enrichment (optional) | |
| TMDB_LANGUAGE | No | Language for localization (e.g., en-US, ru-RU) (optional) | |
| TMDB_API_TOKEN | Yes | TMDB v4 Read Access Token (required) |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Query movies, TV shows and people from The Movie Database (TMDB). Typical flow: use search_movies / search_tv / search_people (or search_multi when the type is unknown) to find an entity and its TMDB id, then get_movie / get_tv / get_person for full details, or get_movie_credits / get_tv_credits for cast & crew. get_trending surfaces what's popular now. get_movie and get_tv include IMDb/Rotten Tomatoes/Metacritic ratings (via OMDb) by default; use the standalone get_ratings only when you have just an IMDb id or a raw title. TMDB needs TMDB_API_TOKEN; rating enrichment needs OMDB_API_KEY (tools report clearly when unset).
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| prompts | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| search_moviesA | Search TMDB movies by title; returns compact summaries with the TMDB id that the other movie tools (get_movie, get_movie_credits, …) require, plus pagination info. Use this over search_multi when you already know the result is a movie. |
| search_tvA | Search TMDB TV shows by name; returns compact summaries with the TMDB id that get_tv and the other TV tools require. Use this over search_multi when you already know the result is a TV show. |
| search_multiA | Search movies, TV shows and people in one call. Each result carries a media_type ('movie' | 'tv' | 'person') so you can route to the right get_* tool. Use when the user's query could be any of these; if you already know the type, search_movies/search_tv/search_people are more precise. |
| search_peopleA | Search TMDB people (actors, directors, crew) by name; returns the TMDB id needed by get_person plus their top 5 best-known titles (known_for). Use this over search_multi when you already know the result is a person. |
| search_keywordsA | Resolve keyword names to TMDB keyword ids (e.g. 'time travel', 'based on true story'). Feed the ids into discover_movies/discover_tv via with_keywords / without_keywords. |
| search_companiesA | Resolve a production company's name to its TMDB numeric id (e.g. 'A24', 'Pixar'). Feed the id into discover_movies/discover_tv via with_companies. Company names aren't unique: TMDB can have several unrelated companies with the same name (e.g. two different 'A24's, one US and one GB), so check origin_country and logo_url to tell rows apart when a name matches more than one. |
| search_collectionsA | Resolve a franchise/series name (e.g. 'harry potter', 'james bond') to its TMDB collection id (TMDB's grouping of a movie series' films). Pass the id to get_collection for every part in release order. Use this when you only have the franchise name; if you already have one of its movies, get_movie's |
| search_watch_providersA | Resolve a streaming/rental/purchase service's name (e.g. 'Netflix', 'Disney Plus') to its TMDB numeric provider id. Feed the id into discover_movies/discover_tv's with_watch_providers, with the same watch_region, to find top titles on that service. TMDB has no name-based lookup for this, only numeric ids, and there are hundreds of providers (296 in the US), so don't guess an id. A provider's id, and whether it's offered at all, can differ by country (checked live: Amazon Prime Video is 9 in the US, Germany and Japan but 119 in France, India and Brazil), so search in the country you'll filter in. |
| get_movieA | Get full details for one movie by TMDB id: overview, genres, keywords ( |
| get_tvA | Get full details for one TV show by TMDB id: overview, genres, keywords ( |
| get_moviesA | Get a compact card (title, year, genres, vote average, and opt-in ratings) for 1-20 movies by TMDB id in one call. Trimmed: no overview, cast, budget, certifications, production companies, etc. Use it for a single id too when you only need that headline info, not just for checking many at once. Call get_movie instead for the full details of a title (including region-specific certification). An id that fails to load (unknown, or hit by an upstream error such as a rate limit) never fails the whole call: that entry comes back |
| get_tv_showsA | Get a compact card (name, year, genres, vote average, season/episode counts, and opt-in ratings) for 1-20 TV shows by TMDB id in one call. A quick way to spot short/miniseries shows (low episode count) across many candidates without a per-title get_tv call. Otherwise trimmed: no overview, episode list, networks, certifications, etc. Use it for a single id too when you only need that headline info, not just for checking many at once. Call get_tv instead for the full details of a title (including region-specific certification). An id that fails to load (unknown, or hit by an upstream error such as a rate limit) never fails the whole call: that entry comes back |
| get_personA | Get full details for one person by TMDB id: biography, birthday/deathday, department, and links (TMDB + IMDb). Does not include filmography; use get_person_credits for that. Get the id from search_people or a credits list. |
| get_movie_creditsA | List the top-billed cast (up to 20) and the headline crew (director, writers, composer, DoP, …) of a movie by TMDB id. Get the id from search_movies. |
| get_tv_creditsA | List a TV show's cast and key crew across its whole run, by TMDB id: up to 20 cast members ranked by how many episodes they appear in (each with their main character and episode_count), plus up to 5 people per key crew job — Director, Writer, Teleplay, Story, Executive Producer, Producer, Original Music Composer, Director of Photography, ranked by episode_count, so 'who directed most of it' is the first Director listed. Creators aren't listed here; use get_tv's |
| get_movie_recommendationsA | Get movies TMDB recommends for the given movie id, based on co-viewing/personalization data (what users who liked this also liked), usually the more thematically relevant list. Prefer this over get_similar by default; get_similar matches on shared genres/keywords, a blunter heuristic that can surface tonally unrelated titles. Get the id from search_movies. |
| get_tv_recommendationsA | Get TV shows TMDB recommends for the given show id, based on co-viewing/personalization data (what users who liked this also liked), usually the more thematically relevant list. Prefer this over get_similar by default; get_similar matches on shared genres/keywords, a blunter heuristic that can surface tonally unrelated titles. Get the id from search_tv. |
| get_similarA | Get titles TMDB considers similar to a given movie or TV show, based on shared genres and keywords. This is a blunter heuristic than get_movie_recommendations/get_tv_recommendations' behavioral (co-viewing) data, so results are often thematically noisy (checked live: The Matrix's first page mixes Videodrome and Dune with The Man with the Golden Gun). Returned in TMDB's order, up to 20 per page (adult/softcore titles are dropped, as on every list TMDB doesn't filter itself). The list runs into the whole catalog (total_results 20001 for The Matrix), so only the first page or two are worth reading. Try recommendations first for thematically closer picks; use this when you specifically want genre/keyword-adjacent titles. Get the id from search_movies/search_tv. |
| get_reviewsA | Get user reviews for a movie or TV show: author, that reviewer's own 0-10 |
| get_collectionA | Get a movie collection/franchise and all its parts in release order (e.g. the whole 'The Dark Knight Collection'). Get the collection id from search_collections (by franchise name) or from a movie's |
| get_person_creditsA | List the movies and TV shows a person is known for (cast roles and crew jobs; adult/softcore titles left out), most popular first, capped to the top 25 of each by default. Talk-show/awards-show guest appearances ('Self'/'Himself'/'Herself', plus any cast credit on a TV talk or news show) and repeat entries for the same title are excluded so the list stays about actual roles. A cameo credited under the person's own name is kept, since TMDB marks it no differently from a real role (checked live: Tom Hanks's top cast row is The Simpsons as 'Tom Hanks (voice)'). A title with several crew jobs (writer AND director AND producer on one film) counts once against the crew cap. Cast entries include a vote_average; crew entries (director, writer, …) do not, so call get_movie/get_tv on the id for a crew credit's own vote_average. Pass department (e.g. 'Directing') to restrict crew to just that role: the reliable way to get someone's complete filmography in one department when their other departments would compete for the same cap. For a handful of very prolific people even that isn't enough (e.g. 50+ directing credits), so raise |
| get_trendingA | Get what's trending on TMDB. media_type selects movies, TV, people, or all; time_window is the trending period (today vs this week). Good for 'what's popular right now'. Each result row carries its own media_type ('movie' | 'tv' | 'person'); check it to route to the right get_* tool, especially when media_type is left at 'all'. |
| get_movie_releasesA | List movies in cinemas now (list='now_playing') or opening soon (list='upcoming') in one country, for 'what's playing in theaters' or 'what comes out next month'. Use get_trending for overall popularity regardless of release, discover_movies for an arbitrary date range. |
| get_movie_genresA | List TMDB movie genres with their numeric ids and names (reference data; rarely changes). Feed the ids into discover_movies' with_genres/without_genres. |
| get_tv_genresA | List TMDB TV genres with their numeric ids and names (reference data; rarely changes). Feed the ids into discover_tv's with_genres/without_genres. |
| discover_moviesA | Find movies by structured filters instead of a title query: genres (include/exclude), year or release-date range, TMDB vote-average range, vote count, runtime range, original language, cast/crew/people, companies (include/exclude), origin country, keywords (include/exclude), watch providers (include/exclude) and access model (subscription/rent/buy/free/ads), certification, a release window in one country by release type (any_release_date_gte/lte + region + with_release_type, e.g. 'movies in German cinemas this month'), an adult-content toggle, and sort order. certification/certification_country/watch_region/with_release_type/region have pairing rules; see their own field descriptions. Use for 'popular sci-fi from the 1990s with a TMDB vote average above 7 available on Netflix', or for a specific person's work in one genre ('which of this director's/actor's/composer's films are animated') via with_crew/with_cast/with_people + with_genres together; get_person_credits has no genre filter, so this combination is the right tool for that question. Resolve ids with get_movie_genres, search_people, search_keywords, search_companies, search_watch_providers. |
| discover_tvA | Find TV shows by structured filters: genres (include/exclude), first-air year or date range, TMDB vote-average range, vote count, runtime, language, origin country, companies (include/exclude), networks, keywords (include/exclude), watch providers (include/exclude) and access model (subscription/rent/buy/free/ads), episodes airing in a date range (air_date_gte/lte), type, status, certification, an adult-content toggle, sort. Not cast/crew/person: this tool doesn't accept those params for TV at all (a validation error, not a silent no-op), because TMDB's own /discover/tv would silently ignore them, unlike /discover/movie. To find TV shows featuring someone, call get_person_credits and filter its results to media_type 'tv'. certification/certification_country/watch_region have pairing rules; see their own field descriptions. The TV counterpart of discover_movies; use with_networks for 'HBO shows', with_type='Miniseries' for short/limited series (e.g. 'best miniseries to binge in a weekend'), with_status='Ended' to exclude shows still airing, certification='TV-Y7' + certification_country='US' for 'shows appropriate for a young kid'. Resolve ids with get_tv_genres, search_companies, search_keywords, search_watch_providers. |
| get_watch_providersA | Find where a movie or TV show can be streamed, rented or bought in a given country (JustWatch data via TMDB). Returns provider names per access type for that country; with no data there, returns |
| get_videosA | List trailers, teasers and clips for a movie or TV show; YouTube entries include a watch URL. Get the id from search_movies/search_tv. Returns videos in the server's configured TMDB_LANGUAGE (default 'en-US') plus English, the title's original language (e.g. Spirited Away's Japanese trailer) and untagged ones; each entry's |
| find_by_imdb_idA | Resolve an IMDb id (e.g. 'tt0133093') to TMDB entities: returns matching movie, TV, person and TV-episode results. Use when you only have an IMDb id and need the TMDB id for the other tools. IMDb also gives individual episodes 'tt' ids (e.g. Breaking Bad's pilot 'tt0959621'); those land in tv_episode_results as show_id + season_number + episode_number, ready for get_tv_episode. An unknown id comes back with every list empty. |
| get_tv_seasonA | Get one season of a TV show (by show id + season number): overview and the episode list with air dates, runtimes and TMDB vote averages, capped at 50 episodes ( |
| get_tv_episodeA | Get one episode of a TV show by show id + season number + episode number: overview, air date, runtime, TMDB vote average ( |
| get_ratingsA | Look up IMDb, Rotten Tomatoes and Metacritic ratings, an awards summary and OMDb's own age rating ( |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| recommend_similar | Plan a merged, ranked shortlist of movies/TV similar to a given title, using TMDB's similarity/recommendation data (with discover as fallback) rather than model memory. Use instead of calling get_similar/get_movie_recommendations yourself; call those directly only when you already have a TMDB id and just want its raw candidate list. |
| top_by_entity | Rank a person's or studio's best-regarded movies/TV, optionally within one genre — 'A24's top movies', 'Tarantino's best films', 'which of Joe Hisaishi's scores are for animated films'. Resolves the name to a TMDB id (search_people/search_companies), then ranks via discover_movies/discover_tv (a person's TV work goes through get_person_credits, since discover_tv can't filter by person). Use instead of doing that multi-step lookup yourself. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 33 tools
Most tools have a clearly distinct role, and the descriptions explicitly disambiguate the risky pairs (search_movies vs search_multi, get_movie vs get_movies, get_movie_recommendations vs get_similar, get_movie_releases vs discover_movies vs get_trending). The remaining hazard is naming-level: singular/plural pairs like get_movie/get_movies and get_tv/get_tv_shows look interchangeable at a glance even though the descriptions define one as full detail and the other as a batch card.
The surface follows a predictable verb_noun scheme (get_movie, search_tv, discover_movies, get_tv_episode, get_watch_providers), which makes the set easy to scan. Minor deviations exist: find_by_imdb_id uses 'find' instead of get/search, and get_similar/get_trending omit the noun.
33 tools is heavy and sits in the 'too many' band, but the TMDB domain is genuinely broad (movies, TV, seasons, episodes, people, credits, collections, providers, genres, keywords, ratings, discovery), so nearly every tool maps to a real capability rather than filler. It is still borderline: a few batch/detail pairs (get_movie vs get_movies, get_tv vs get_tv_shows) and the four search_* tools could arguably be consolidated.
Coverage is exceptional: search across all media types, full detail plus compact batch cards, credits for movies/TV/people, recommendations and similar, reviews, collections, trending, two rich discover endpoints, watch providers, videos, seasons and episodes, plus external ratings, genre/keyword/company/provider resolution and IMDb-id resolution. Only minor read paths are absent (images/posters, company/network detail endpoints, account lists), which agents can work around.