Skip to main content
Glama
TMDB MCP Server

TMDB MCP Server

TMDB MCP Server

npm version CI license: MIT MCP Registry tmdb-mcp MCP server

An MCP server for The Movie Database (TMDB): search and look up movies, TV shows and people, and read IMDb / Rotten Tomatoes / Metacritic ratings (via OMDb) in the same call.

The server speaks standard MCP over stdio, so it works with any MCP client (Claude Desktop/Code, Cursor, VS Code, Cline, …).

Once connected, ask your agent in plain language. You need a free TMDB token; see Getting your credentials:

"Search for the movie Dune: Part Two and show its overview, genres and runtime."
"What movies are trending this week?"
"Find TV shows similar to Breaking Bad."
"Who directed Oppenheimer? Show the main cast."
"What's Greta Gerwig's filmography?"
"Discover highly-rated sci-fi movies from the 2010s, sorted by rating."
"Where can I stream The Bear in the US?"
"Show me the trailer for Deadpool & Wolverine."
"List the episodes of Severance season 1."
"Which movie has IMDb id tt0111161?"
"Search for people named Zendaya."
"Get the year, genres and rating for these five movies in one go: Dune, Dune: Part Two, Arrival, Sicario and Blade Runner 2049."
"What are the best limited series to binge over a weekend?"
"What TV shows can I watch with my 9-year-old kid?"
"What movies has A24 produced?"
"What are Tarantino's best-rated crime movies?"
"Who composed the music for My Neighbor Totoro, and what else has he scored?"

With an optional (free) OMDb key, ratings are added too:

"What are the IMDb, Rotten Tomatoes and Metacritic scores for The Godfather?"
"Compare the critics' scores for Barbie and Oppenheimer."

Install

Add it to your MCP client's config. The only required credential is a TMDB v4 Read Access Token; OMDB_API_KEY (ratings) and TMDB_LANGUAGE / TMDB_REGION (localization) are optional.

Via npx (no install):

{
  "mcpServers": {
    "tmdb": {
      "command": "npx",
      "args": ["-y", "tmdb-mcp"],
      "env": {
        "TMDB_API_TOKEN": "your-tmdb-v4-read-access-token (required)",
        "OMDB_API_KEY": "your-omdb-key (optional: IMDb/RT/Metacritic ratings)",
        "TMDB_LANGUAGE": "en-US (optional: localize, e.g. ru-RU)",
        "TMDB_REGION": "US (optional: the user's country, e.g. RU)"
      }
    }
  }
}

Replace each value with your own. Only TMDB_API_TOKEN is required; delete the lines marked optional if you don't need them.

As a .mcpb bundle (easiest for Claude Desktop): download tmdb-mcp.mcpb from the latest release, then open it or drag it into Claude Desktop's Extensions. The bundle is self-contained (no Node or npm needed); enter the token and the optional fields in the install dialog. To update, download and reinstall.

From source: git clone, then npm ci && npm run build, and point the client at it with "command": "node", "args": ["/ABS/PATH/tmdb-mcp/dist/index.js"] and the same env as above.

See docs/clients.md for per-client details and all tunables.

Related MCP server: moviefinder-mcp

What it does

Tool

Purpose

search_movies / search_tv / search_people

Find titles/people by name → TMDB id

search_multi

Search movies, TV and people at once (each row has a media_type)

get_movie / get_tv

Full details, keywords + IMDb/RT/Metacritic ratings (toggle with include_ratings)

get_movies / get_tv_shows

Compact card(s) (title/year/genres/vote average, ratings opt-in) for 1-20 ids in one call

get_person

Biography, department, links

get_movie_credits / get_tv_credits

Top-billed cast and headline crew (TV: whole run, ranked by episode count)

get_movie_recommendations / get_tv_recommendations

Recommendations from co-viewing data (what fans also liked)

get_similar

Algorithmically similar titles (media_type + id)

get_trending

What's popular now (movies / TV / people, day or week)

get_movie_releases

Movies in cinemas now (now_playing) or opening soon (upcoming) in a country, with TMDB's date window

get_movie_genres / get_tv_genres

Genre id ↔ name reference

discover_movies

Filter by genre, date range, rating, cast/crew, companies, origin country, keywords, providers (+/-, access type), certification, regional release dates

discover_tv

Same, plus networks/type/status and episodes airing in a date range, but no cast/crew/person or regional release-date filter (use get_person_credits for people)

get_watch_providers

Where to stream/rent/buy, by region (JustWatch via TMDB)

get_person_credits

A person's filmography (cast & crew)

get_videos

Trailers/teasers/clips (YouTube links)

get_reviews

User reviews (author, rating, text) for a movie/TV

get_collection

A movie franchise/collection and its parts, in release order

find_by_imdb_id

Resolve an IMDb id → TMDB movie/TV/person/episode

get_tv_season / get_tv_episode

Season episode list / single-episode details

search_keywords

Resolve keyword names → ids for discover_*

search_companies

Resolve a production company name → id for discover_*'s with_companies

search_collections

Resolve a franchise name (e.g. 'harry potter') → collection id for get_collection

search_watch_providers

Resolve a streaming/rental service name (e.g. 'Netflix') → id for discover_*'s with_watch_providers

get_ratings

IMDb/RT/Metacritic ratings by IMDb id or title (standalone)

Prompts. The server also exposes two MCP prompts. recommend_similar (title, optional media_type, optional count) plans a search for titles similar to one the user liked, using get_similar / get_movie_recommendations / get_tv_recommendations / discover_movies / discover_tv instead of the model's own knowledge. top_by_entity (name, optional entity_type, genre, media_type, count) finds the best-regarded titles from a person or a production company/studio (e.g. "A24's top movies" or "Tarantino's best crime films") via discover_movies/discover_tv. For a person's TV work it falls back to get_person_credits, because TMDB's /discover/tv can't filter by person at all.

Backbone vs. enrichment. TMDB is the primary source (search, metadata, people, trending). OMDb is optional enrichment: get_movie/get_tv pass the imdb_id TMDB returns to OMDb, so ratings come back in one call. The same call returns a free-text awards summary (major-award wins/nominations, e.g. Oscars for a film or Emmys for a show; it covers the title as a whole, with no attribution to individuals) and OMDb's own age rating (ratings.rated, separate from this server's certification). Without an OMDb key the TMDB data still works, and the ratings field reports that OMDb is unconfigured.

Localization. TMDB_LANGUAGE (e.g. ru-RU) and TMDB_REGION (e.g. RU) are the user's default language and country: localized titles/overviews/genre names, and the country for age ratings, cinemas and where to watch (including discover_*'s watch filters). Tools that need them publish them as their language/region/watch_region defaults (discover's watch_region names the value in its description), and the agent can pass the user's own per call. search_movies/search_tv/search_multi/search_people/ search_collections, get_movie/get_tv/get_movies/get_tv_shows/get_person, get_collection, get_movie_releases and discover_movies/discover_tv take language.

Getting your credentials

The TMDB token is required and the OMDb key is optional. Both are free.

  1. TMDB token (required). Create a free account at themoviedb.org, then open Settings → API and request an API key (personal use). Copy the "API Read Access Token" (the long v4 token, not the short v3 key) into TMDB_API_TOKEN. It is sent as Authorization: Bearer ….

  2. OMDb key (optional). Grab a free key at omdbapi.com/apikey.aspx (the free tier is enough), click the activation link in the email, and set OMDB_API_KEY. This unlocks get_ratings and the IMDb / Rotten Tomatoes / Metacritic scores in movie and TV details. Everything else works without it.

Put these in your MCP client config's env block (see docs/clients.md for per-client snippets). Never commit them. TMDB_LANGUAGE / TMDB_REGION optionally set default locale/region (e.g. ru-RU, RU).

Advanced tuning (env-only, no install-UI equivalent)

The defaults are sensible; change them only if you need to. These variables are not in Claude Desktop's install form, so CLI/Docker users set them in the environment.

Variable

Default

Purpose

TMDB_BASE_URL

https://api.themoviedb.org/3

Override TMDB's API base (e.g. a proxy)

OMDB_BASE_URL

https://www.omdbapi.com

Override OMDb's API base

HTTP_TIMEOUT_MS

15000

Per-request timeout before aborting

HTTP_RETRIES

2

Retries on a transient upstream failure

TMDB_MIN_INTERVAL_MS

60

Minimum spacing between TMDB requests

OMDB_MIN_INTERVAL_MS

0

Minimum spacing between OMDb requests

CACHE_TTL_MS

300000

How long cached responses stay fresh

CACHE_MAX_STALE_MS

86400000

How long past that a cached response may stand in for an unreachable upstream

LOG_LEVEL

info

debug | info | warn | error | silent

If TMDB/OMDb is briefly down and a tool serves a cached but expired response instead of failing, the result carries _meta: {"io.github.Grinv.tmdb-mcp/stale": {"age_seconds": N}} (how old the data is) alongside the normal data, so a client can tell a degraded answer from a fresh one. "io.github.Grinv.tmdb-mcp/partial": true likewise flags a result with a part missing.

Develop

npm install
npm run build        # type-check + bundle to dist/index.js
npm test             # node:test (mocked, offline)
npm run lint
npm run format
npm run check:api    # live upstream health-check (needs the env credentials)
npm run inspector    # run under the MCP Inspector

Runtime requires Node ≥ 22.18. Contributor/agent guidance lives in AGENTS.md.

Updating

  • .mcpb bundle: download the new bundle from the releases page and reinstall.

  • From source: git pull && npm ci && npm run build.

  • npx: unpinned npx -y tmdb-mcp fetches the latest on the next run.

This product uses the TMDB API but is not endorsed or certified by TMDB.

Privacy Policy

tmdb-mcp runs entirely on your own machine and collects no data of its own. See PRIVACY.md for exactly what it sends to TMDB/OMDb and what (if anything) it stores locally.

Security

Read-only, two fixed upstream hosts, credentials never persisted. See SECURITY.md for the full breakdown and how to report a vulnerability.

License

MIT © Grinv

Available Tools

33 tools
discover_moviesDiscover movies (filters)A
Read-only

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.

Inputs: page, year, region, sort_by, +29 more. Returns: page, results, total_pages, total_results

discover_tvDiscover TV shows (filters)A
Read-only

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.

Inputs: page, year, sort_by, language, +27 more. Returns: page, results, total_pages, total_results

find_by_imdb_idFind by IMDb idA
Read-only

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.

Inputs: imdb_id (required). Returns: tv_results, movie_results, person_results, tv_episode_results

get_collectionGet a movie collectionA
Read-only

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 collection field in get_movie. Adult/softcore parts are left out.

Inputs: id (required), language. Returns: id, name, parts, overview, +1 more

get_movieGet movie detailsA
Read-only

Get full details for one movie by TMDB id: overview, genres, keywords ({id, name}), runtime, budget/revenue, vote average, the age/content rating (certification) for region (falling back to the US rating, then any available country, when region has none; check certification_region to see which one was used), and links (TMDB + IMDb). By default also includes IMDb/Rotten Tomatoes/Metacritic ratings and an awards summary (see include_ratings), plus OMDb's own age rating (ratings.rated, separate from this tool's certification; the two can differ), from OMDb (set include_ratings=false to skip). If unavailable (no OMDB_API_KEY, no imdb_id, or the OMDb lookup fails), ratings degrades to {found:false, reason} instead of failing the call. For titles like this one, get_movie_recommendations is the first stop; to match its themes instead, pass 2-3 distinctive keyword ids to discover_movies' with_keywords joined with ',' (all must match; checked live: The Matrix's 'man vs machine', 'artificial intelligence', 'dystopia' give the Terminator films); '|' broadens to any one. If you only need the headline info (title/year/genres/vote average), for one id or several, use get_movies: it's trimmed and skips the rest of this payload. Get the id from search_movies.

Inputs: id (required), region, language, include_ratings. Returns: id, year, title, genres, +27 more

get_movie_creditsGet movie cast & crewA
Read-only

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.

Inputs: id (required). Returns: cast, crew

get_movie_genresList movie genresA
Read-only

List TMDB movie genres with their numeric ids and names (reference data; rarely changes). Feed the ids into discover_movies' with_genres/without_genres.

Inputs: no named parameters. Returns: genres

get_movie_recommendationsGet movie recommendationsA
Read-only

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.

Inputs: id (required), page. Returns: page, results, total_pages, total_results

get_movie_releasesGet movies in or coming to cinemasA
Read-only

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. region filters to movies with a theatrical release in that country inside the window (a different set per country, not just a re-sort; an unrecognized code such as 'ZZ' returns an empty page, but 'XX' is a real TMDB pseudo-region). Each row's release_date is that country's release date, which can predate the window for a re-release (e.g. a 2014 film re-released this month). The window comes from TMDB and is returned as dates {minimum, maximum} (YYYY-MM-DD; same for every region; roughly the last six weeks for now_playing, the next three weeks for upcoming). TMDB's own order: roughly most popular first, not by date.

Inputs: list (required), page, region, language. Returns: page, dates, results, total_pages, +1 more

get_moviesGet compact movie card(s)A
Read-only

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 {id, found:false, reason} instead, in the same order as ids; read reason before concluding the id doesn't exist.

Inputs: ids (required), language, include_ratings. Returns: results

get_personGet person detailsA
Read-only

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.

Inputs: id (required), language. Returns: id, name, gender, imdb_id, +11 more

get_person_creditsGet person filmographyA
Read-only

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 limit too when department alone still looks short. Use for 'what has this actor/director been in'. This tool has no genre filter; for 'which of X's movies are animated/horror/etc.' use discover_movies, combining with_cast/with_crew/with_people with with_genres. discover_tv can't filter by person at all, so for a person's TV work in one genre, call this tool and check the returned media_type 'tv' entries' genres yourself, e.g. via get_tv_shows. Get the id from search_people.

Inputs: id (required), limit, department. Returns: cast, crew

get_ratingsGet IMDb/RT/Metacritic ratingsA
Read-only

Look up IMDb, Rotten Tomatoes and Metacritic ratings, an awards summary and OMDb's own age rating (rated) from OMDb, by IMDb id (preferred, e.g. 'tt0133093') or by title (+ optional year/type). The awards summary is free text (major-award wins/nominations: Oscars, Emmys, Golden Globes, etc.), not a structured count, and covers the whole film/show, or one episode when given an episode's imdb_id, never one person. Prefer get_movie/get_tv when you have a TMDB id: they already include this. Requires OMDB_API_KEY. One of imdb_id or title is required; omitting both returns an error. A no-match lookup is not an error: it returns {found:false, reason}; a refusal (bad key, exhausted daily quota) is. A title lookup resolves to whichever single entry OMDb picks, reports no runner-up, and cannot be validated, so it can silently return a different work of the same name. Checked live: title:'Halloween' with no year returns the 1978 original (tt0077651, IMDb 7.7, RT 97%), not the 2018 film titled exactly the same (tt1502407, IMDb 6.5, RT 79%). Always read back the returned imdb_id/title/year to confirm which work you got, and pass year (and type) whenever you know them. When you only have a title, prefer search_movies/search_tv → get_movie/get_tv: that path matches by imdb_id and also drops an OMDb hit whose release year is more than two years from TMDB's, which this tool's title path cannot do.

Inputs: type, year, title, imdb_id. Returns: object

get_reviewsGet user reviewsA
Read-only

Get user reviews for a movie or TV show: author, that reviewer's own 0-10 rating if they left one (a single person's score, not the aggregate vote_average and not an IMDb/RT/Metacritic value; it can be null), and the review text, clipped to ~1500 characters. Get the id from search_movies/search_tv.

Inputs: id (required), media_type (required), page. Returns: page, results, total_pages, total_results

get_similarGet similar titlesA
Read-only

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.

Inputs: id (required), media_type (required), page. Returns: page, results, total_pages, total_results

get_tvGet TV show detailsA
Read-only

Get full details for one TV show by TMDB id: overview, genres, keywords ({id, name}), seasons/episodes counts, networks, created_by (the show's creator(s)), status, the age/content rating (certification) for region (falling back to the US rating, then any available country, when region has none; check certification_region to see which one was used), and links. By default also includes IMDb/Rotten Tomatoes/Metacritic ratings and an awards summary (see include_ratings), plus OMDb's own age rating (ratings.rated, separate from this tool's certification; the two can differ), from OMDb (set include_ratings=false to skip). If unavailable (no OMDB_API_KEY, no imdb_id, or the OMDb lookup fails), ratings degrades to {found:false, reason} instead of failing the call. For shows like this one, get_tv_recommendations is the first stop; to match its themes instead, pass 2-3 distinctive keyword ids to discover_tv's with_keywords. A show's keywords are sparser, so ',' (all) often matches only the show itself and '|' (any) is the usual pick (checked live: Breaking Bad's 'drug dealer'|'outlaw' give The Sopranos, Narcos, Peaky Blinders). Set expand_episodes=true to also pull the seasons' episode lists (up to 250 episodes, 50 per season; see that field) instead of calling get_tv_season per season. If you only need the headline info (name/year/genres/vote average, season/episode counts), for one id or several, use get_tv_shows: it's trimmed and skips the rest of this payload. Get the id from search_tv.

Inputs: id (required), region, language, expand_episodes, +1 more. Returns: id, name, type, year, +32 more

get_tv_creditsGet TV cast & crewA
Read-only

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 created_by. For one specific episode's director/writer, use get_tv_episode. Get the id from search_tv.

Inputs: id (required). Returns: cast, crew

get_tv_episodeGet TV episodeA
Read-only

Get one episode of a TV show by show id + season number + episode number: overview, air date, runtime, TMDB vote average (vote_average, TMDB's own 0-10 user score, not an IMDb/RT/Metacritic score; get_movie/get_tv's ratings are whole-show only and this tool makes no OMDb call), guest stars (up to 15) and director/writer. Also returns the episode's own imdb_id/imdb_url; pass that id to get_ratings for this episode's IMDb rating, the only way to get a per-episode IMDb score here. Get the show id from search_tv.

Inputs: id (required), season_number (required), episode_number (required). Returns: crew, name, imdb_id, air_date, +8 more

get_tv_genresList TV genresA
Read-only

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.

Inputs: no named parameters. Returns: genres

get_tv_recommendationsGet TV recommendationsA
Read-only

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.

Inputs: id (required), page. Returns: page, results, total_pages, total_results

get_tv_seasonGet TV seasonA
Read-only

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 (episode_count reports the true total). Per-episode vote_average is TMDB's own 0-10 user score, not the IMDb/RT/Metacritic scores get_movie/get_tv return as ratings, which are whole-show only; this tool makes no OMDb call, and TMDB's season payload carries no per-episode IMDb ids either, so call get_tv_episode when you need one episode's imdb_id for get_ratings. Season 0 is usually specials, which can run to hundreds of bonus clips on a long-running show. Use get_tv with expand_episodes=true instead if you need every season's episodes in one call. Get the show id from search_tv.

Inputs: id (required), season_number (required). Returns: name, air_date, episodes, overview, +3 more

get_tv_showsGet compact TV show card(s)A
Read-only

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 {id, found:false, reason} instead, in the same order as ids; read reason before concluding the id doesn't exist.

Inputs: ids (required), language, include_ratings. Returns: results

get_videosGet trailers & videosA
Read-only

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 language (ISO-639-1) says which. No per-call language override.

Inputs: id (required), media_type (required). Returns: results

get_watch_providersWhere to watchA
Read-only

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 available:false plus available_regions to retry with. Get the id from search_movies/search_tv.

Inputs: id (required), media_type (required), region. Returns: object

search_collectionsSearch movie collectionsA
Read-only

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 collection field carries the same id. Movies only: collection parts are movies, and a TV series name finds nothing (e.g. 'breaking bad' → 0 results). A name can match several collections ('star wars' also returns 'LEGO Star Wars Collection' and other spin-off groupings); pick by name/overview. Rows are id, name, overview, poster_url, localized per language (e.g. 'de-DE' → 'Harry Potter Filmreihe').

Inputs: query (required), page, language. Returns: page, results, total_pages, total_results

search_companiesSearch production companiesA
Read-only

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.

Inputs: query (required), page. Returns: page, results, total_pages, total_results

search_keywordsSearch keywordsA
Read-only

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.

Inputs: query (required), page. Returns: page, results, total_pages, total_results

search_moviesSearch moviesA
Read-only

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. year/release_date are the original (primary) release, as everywhere except get_movie_releases, which shows the chosen country's date.

Inputs: query (required), page, year, language, +2 more. Returns: page, results, total_pages, total_results

search_multiSearch everythingA
Read-only

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.

Inputs: query (required), page, language, include_adult. Returns: page, results, total_pages, total_results

search_peopleSearch peopleA
Read-only

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.

Inputs: query (required), page, language, include_adult. Returns: page, results, total_pages, total_results

search_tvSearch TV showsA
Read-only

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.

Inputs: query (required), page, year, language, +1 more. Returns: page, results, total_pages, total_results

search_watch_providersSearch streaming/rental providersA
Read-only

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.

Inputs: query (required), media_type (required), page, watch_region. Returns: page, results, total_pages, total_results

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 33 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness5/5

    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.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      An MCP server that wraps The Movie Database (TMDB) API, enabling search for movies and TV shows, retrieval of movie details, recommendations, similar movies, trending content, streaming providers, and movie discovery.
      8
      -
    • F
      license
      A
      quality
      D
      maintenance
      An MCP server that wraps the TMDB API, enabling search of movies and TV shows, retrieval of details, trending titles, recommendations, and streaming provider information.
      8
      -
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for the OMDb API - search movies, series, and episodes from any MCP-compatible client.
      5
      12 PyPI
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      A local, read-only MCP server for discovering movies and TV series from The Movie Database (TMDB). It provides tools for search, details, trending, discovery, and related content.
      29
      66 npm
      MIT