tmdb-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| TMDB_API_KEY | No | TMDB v3 API key, sent as the api_key query parameter. One of TMDB_API_KEY or TMDB_READ_ACCESS_TOKEN is required. | |
| TMDB_LANGUAGE | No | Default response language, e.g. en-US (default), fr-FR, he-IL. Every read tool also takes a language argument. | en-US |
| TMDB_PASSWORD | No | TMDB password for account tools. Use with TMDB_USERNAME, or use TMDB_SESSION_ID instead. | |
| TMDB_USERNAME | No | TMDB username for account tools. Use with TMDB_PASSWORD, or use TMDB_SESSION_ID instead. | |
| TMDB_SESSION_ID | No | An existing v3 session ID for account tools, used instead of username and password. | |
| TMDB_READ_ACCESS_TOKEN | No | TMDB API Read Access Token, sent as a Bearer header. Used instead of the API key when both are set. One of TMDB_API_KEY or TMDB_READ_ACCESS_TOKEN is required. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Tools for The Movie Database (TMDB). Use search or find_by_external_id to get TMDB IDs, then the get_* tools for details; discover_movies and discover_tv filter by genre, people, dates, ratings and streaming providers. Image fields such as poster_path, backdrop_path, still_path and profile_path are relative paths: build URLs as https://image.tmdb.org/t/p/{size}{path} with size w185, w342, w500, w780 or original. Account tools (get_account*, rate, delete_rating, set_favorite, set_watchlist and the list tools) act on the configured TMDB user. Lists hold movies only.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| searchA | Search TMDB by text. type=multi (default) searches movies, TV shows and people together; pick a specific type to narrow it. Returns paged results with the IDs the other tools take. |
| get_movieA | Full details for a movie: overview, runtime, genres, release date, budget, ratings. Use append to embed credits, videos, recommendations, reviews, watch providers and more in one call. |
| get_tv_showA | Full details for a TV show: overview, seasons, networks, status, next/last episode. Use append to embed credits, videos, recommendations, content ratings and more. |
| get_tv_seasonB | Details for one season of a TV show, including its episode list. |
| get_tv_episodeB | Details for a single TV episode: air date, overview, guest stars, crew, rating. |
| get_personA | Details for a person (actor, director, crew): biography, birthday, known for. Use append for movie_credits, tv_credits or combined_credits to get their filmography. |
| get_collectionB | A movie collection (franchise) with all of its movies, e.g. the Lord of the Rings collection. |
| get_trendingC | Trending movies, TV shows and/or people for the day or the week. |
| get_movie_listC | A curated movie chart: popular, top_rated, now_playing (in theaters) or upcoming. |
| get_tv_listB | A curated TV chart: popular, top_rated, airing_today or on_the_air (airing in the next 7 days). |
| discover_moviesA | Find movies by filters instead of text: genres, people, companies, keywords, release dates, ratings, runtime, streaming availability. Use get_genres for genre IDs and search for person, company or keyword IDs. |
| discover_tvB | Find TV shows by filters instead of text: genres, networks, companies, keywords, air dates, ratings, status, streaming availability. |
| get_genresA | The official genre list with IDs for movies or TV, for use with discover filters. |
| find_by_external_idB | Look up TMDB movies, shows, episodes or people by an external ID such as an IMDb ID (tt0111161, nm0000151) or a TVDB ID. |
| get_watch_providersA | Where a movie or TV show can be streamed, rented or bought, per country (data from JustWatch). Pass region to get a single country. |
| get_recommendationsA | Movies or shows related to a given one. source=recommendations uses TMDB user behaviour; source=similar uses genres and keywords. |
| get_accountB | Details of the configured TMDB account: ID, username, name, language and country. |
| get_account_statesB | Whether a movie, TV show or episode is in my favorites or watchlist, and my rating for it if I rated it. |
| get_account_itemsA | Paged list of my favorite, watchlisted or rated movies or TV shows. media_type=episode is only valid with kind=rated. |
| rateA | Rate a movie, TV show or episode on my account, from 0.5 to 10 in steps of 0.5. Replaces any earlier rating. |
| delete_ratingC | Remove my rating from a movie, TV show or episode. |
| set_favoriteA | Mark a movie or TV show as a favorite (favorite=true) or remove it from favorites (favorite=false). |
| set_watchlistA | Add a movie or TV show to my watchlist (watchlist=true) or remove it (watchlist=false). |
| get_account_listsB | The custom lists I created on TMDB, with their IDs and item counts. |
| get_listA | A TMDB list with its items. Pass movie_id to also check whether that movie is on the list. |
| create_listA | Create a new custom list on my account. Returns the new list_id. TMDB v3 lists hold movies only. |
| add_to_listC | Add a movie to one of my lists. |
| remove_from_listC | Remove a movie from one of my lists. |
| clear_listA | Remove every item from one of my lists. The list itself is kept. |
| delete_listB | Permanently delete one of my lists. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 30 tools
Most tools have clearly distinct resource+action targets: search vs discover_movies/discover_tv are separated by text-vs-filters, and remove_from_list/clear_list/delete_list are well delineated. The only fuzzy area is the list/account cluster (get_account_lists vs get_list vs get_account_items), where an agent could momentarily misselect, but descriptions resolve it.
Predominantly verb_noun / get_noun (get_movie, get_tv_show, create_list, add_to_list, set_watchlist), which is readable and predictable. Minor deviations exist: bare verbs 'search' and 'rate', and the removal verbs alternate between remove_, clear_, and delete_.
30 tools is heavy, though the TMDB surface genuinely spans movies, TV, seasons, episodes, people, account, ratings, and lists, so most tools carry their weight. It still sits well above a comfortable 10-15 range and could be trimmed via append-style consolidation (e.g. the many list operations).
Coverage is broad: discovery, text search, external-ID lookup, detail endpoints with append, trending/charts, watch providers, recommendations, ratings, favorites, watchlist, and full custom-list lifecycle. Minor gap: discover filters require company/keyword IDs but search only offers multi/movie/tv/person types, so those IDs are awkward to obtain.