TMDB MCP Server
A read-only MCP server for The Movie Database (TMDB) that lets an agent search and look up movies, TV shows and people — with optional IMDb/Rotten Tomatoes/Metacritic ratings from OMDb — over stdio, for use in any MCP client.
Search movies, TV shows, people, or all at once (
search_movies/search_tv/search_people/search_multi), plus keyword, company, collection and streaming-provider lookups to resolve names → TMDB ids.Full details for a movie or TV show: overview, genres, keywords, runtime/seasons, budget/revenue, networks, creators, certifications, links, and optional OMDb ratings, awards summary and age rating (
get_movie/get_tv).Batch compact cards for 1–20 ids in one call (
get_movies/get_tv_shows); person bios (get_person) and full filmographies (get_person_credits).Cast & crew lists for movies and TV shows (
get_movie_credits/get_tv_credits).Discovery & recommendations: filter-based
discover_movies/discover_tv(genre, dates, ratings, cast/crew, companies, countries, keywords, providers, certification, networks, type/status), co-viewing recommendations, and genre/keyword-based similar titles.What's hot / in cinemas: trending titles, now-playing and upcoming cinema releases by country.
Watch info: where to stream/rent/buy by region; trailers and clips (
get_videos); user reviews.Franchises & episodes: movie collections in release order, season episode lists, single-episode details (incl. per-episode IMDb id), and IMDb-id resolution (
find_by_imdb_id).Standalone ratings by IMDb id or title via OMDb (
get_ratings), and genre id reference lists.Two MCP prompts (
recommend_similar,top_by_entity) plus localization (language/region) and stale/partial-result metadata flags.
Provides IMDb ratings enrichment via OMDb, included in movie/TV details when available.
Provides Metacritic ratings enrichment via OMDb, included in movie/TV details when available.
Provides Rotten Tomatoes ratings enrichment via OMDb, included in movie/TV details when available.
Primary source for movie, TV show, and person metadata; provides search, details, credits, recommendations, trending, discover, watch providers, and more via TMDB API.
Provides links to trailers, teasers, and clips for movies and TV shows via the get_videos tool.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@TMDB MCP Server find 'The Matrix' and get its ratings"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
TMDB 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_TOKENis 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 |
| Find titles/people by name → TMDB id |
| Search movies, TV and people at once (each row has a |
| Full details, keywords + IMDb/RT/Metacritic ratings (toggle with |
| Compact card(s) (title/year/genres/vote average, ratings opt-in) for 1-20 ids in one call |
| Biography, department, links |
| Top-billed cast and headline crew (TV: whole run, ranked by episode count) |
| Recommendations from co-viewing data (what fans also liked) |
| Algorithmically similar titles ( |
| What's popular now (movies / TV / people, day or week) |
| Movies in cinemas now ( |
| Genre id ↔ name reference |
| Filter by genre, date range, rating, cast/crew, companies, origin country, keywords, providers (+/-, access type), certification, regional release dates |
| Same, plus networks/type/status and episodes airing in a date range, but no cast/crew/person or regional release-date filter (use |
| Where to stream/rent/buy, by region (JustWatch via TMDB) |
| A person's filmography (cast & crew) |
| Trailers/teasers/clips (YouTube links) |
| User reviews (author, rating, text) for a movie/TV |
| A movie franchise/collection and its parts, in release order |
| Resolve an IMDb id → TMDB movie/TV/person/episode |
| Season episode list / single-episode details |
| Resolve keyword names → ids for |
| Resolve a production company name → id for |
| Resolve a franchise name (e.g. 'harry potter') → collection id for |
| Resolve a streaming/rental service name (e.g. 'Netflix') → id for |
| 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.
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 asAuthorization: Bearer ….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 unlocksget_ratingsand 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 |
|
| Override TMDB's API base (e.g. a proxy) |
|
| Override OMDb's API base |
|
| Per-request timeout before aborting |
|
| Retries on a transient upstream failure |
|
| Minimum spacing between TMDB requests |
|
| Minimum spacing between OMDb requests |
|
| How long cached responses stay fresh |
|
| How long past that a cached response may stand in for an unreachable upstream |
|
|
|
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 InspectorRuntime requires Node ≥ 22.18. Contributor/agent guidance lives in AGENTS.md.
Updating
.mcpbbundle: download the new bundle from the releases page and reinstall.From source:
git pull && npm ci && npm run build.npx: unpinned
npx -y tmdb-mcpfetches 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 toolsdiscover_moviesDiscover movies (filters)ARead-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)ARead-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 idARead-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 collectionARead-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 detailsARead-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 & crewARead-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 genresARead-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 recommendationsARead-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 cinemasARead-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)ARead-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 detailsARead-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 filmographyARead-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 ratingsARead-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 reviewsARead-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 titlesARead-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_trendingGet trending titlesARead-only
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'.
Inputs: page, media_type, time_window. Returns: page, results, total_pages, total_results
get_tvGet TV show detailsARead-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 & crewARead-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 episodeARead-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 genresARead-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 recommendationsARead-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 seasonARead-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)ARead-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 & videosARead-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 watchARead-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 collectionsARead-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 companiesARead-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 keywordsARead-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 moviesARead-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 everythingARead-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 peopleARead-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 showsARead-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 providersARead-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
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.
Maintenance
Related MCP Connectors
OMDb MCP — IMDB-derived movie / TV / episode data (BYO key)
Unofficial Movies MCP — wraps iTunes Search API (movies, free, no auth) and TVmaze API (TV shows…
Unlock a world of television with the TV Maze MCP server. Effortlessly search for shows by name or
Related MCP Servers
- FlicenseAqualityDmaintenanceAn 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-
- FlicenseAqualityDmaintenanceAn 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-
- AlicenseAqualityDmaintenanceMCP server for the OMDb API - search movies, series, and episodes from any MCP-compatible client.512 PyPIMIT
- AlicenseBqualityCmaintenanceA 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.2966 npmMIT