tmdb-mcp
Provides tools for interacting with The Movie Database (TMDB) API, covering both catalog reads and account writes. Read tools search movies, TV shows, people, collections, companies and keywords; fetch details with appended credits, videos, images, reviews and release dates; browse seasons and episodes; list trending, popular, top-rated and upcoming titles; run filtered discover queries by genre, cast, crew, company, keyword, dates, rating, runtime or streaming provider; resolve genre IDs, external IDs (IMDb, TVDB, Wikidata) and streaming availability by region. Account tools require TMDB credentials and let you check favorites/watchlist/rating states, read your favorites, watchlist, ratings and custom lists, rate or remove ratings for movies, shows and episodes, toggle favorites and watchlist entries, and create, populate, clear or delete movie lists.
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 where can I stream Dune: Part Two in the US?"
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
An MCP server for The Movie Database (TMDB) with read and write tools: search, details, discover, trending and streaming availability, plus your own ratings, watchlist, favorites and lists.
Built on the MCP TypeScript SDK v2 (
@modelcontextprotocol/server), served over stdio.Speaks the 2026-07-28 protocol revision and still serves 2025-era clients (
initializehandshake) on the same binary.30 tools with input validation (zod) and
readOnlyHint/destructiveHint/idempotentHintannotations, so clients can auto-approve reads and confirm writes.
Tools
Catalog (read-only, API key only)
Tool | What it does |
| Text search across movies, TV, people, collections, companies or keywords ( |
| Movie details; |
| TV show details; |
| One season with its episode list |
| One episode with guest stars and crew |
| Person details; |
| A franchise and all of its movies |
| Trending movies, shows or people for the day or week |
| Popular, top rated, now playing or upcoming movies |
| Popular, top rated, airing today or on the air TV shows |
| Filter movies by genre, cast, crew, company, keyword, dates, rating, runtime, streaming provider (any other TMDB discover parameter via |
| Filter TV by genre, network, dates, status, type, rating, streaming provider |
| Genre IDs for movies or TV |
| Look up by IMDb, TVDB, Wikidata or social IDs |
| Where to stream, rent or buy, for all countries or one |
| Recommended or similar movies and shows |
Your account (needs account credentials)
Tool | Kind | What it does |
| read | Account ID, username, language and country |
| read | Whether a movie, show or episode is favorited, watchlisted or rated by you |
| read | Your favorites, watchlist or ratings for movies, TV or episodes |
| read | Your custom lists |
| read | A list's items; pass |
| write | Rate a movie, show or episode from 0.5 to 10 |
| write | Remove a rating |
| write | Add or remove a favorite |
| write | Add or remove a watchlist item |
| write | Create a list |
| write | Add a movie to a list |
| write | Remove a movie from a list |
| write | Remove every item from a list |
| write | Delete a list |
Related MCP server: moviefinder-mcp
Setup
1. Get TMDB credentials
Create a free account at themoviedb.org.
Request an API key at Settings → API. You get both an API Key and an API Read Access Token; either one works.
For the account tools, also provide your TMDB username and password, or a session ID (see Account access).
2. Add the server to your MCP client
The server installs and builds straight from GitHub with npx, no npm publish needed.
Claude Code
claude mcp add tmdb \
-e TMDB_API_KEY=your_api_key \
-e TMDB_USERNAME=your_username \
-e TMDB_PASSWORD=your_password \
-- npx -y github:matanbaruch/tmdb-mcpClaude Desktop, Cursor and other JSON-configured clients
{
"mcpServers": {
"tmdb": {
"command": "npx",
"args": ["-y", "github:matanbaruch/tmdb-mcp"],
"env": {
"TMDB_API_KEY": "your_api_key",
"TMDB_USERNAME": "your_username",
"TMDB_PASSWORD": "your_password"
}
}
}
}From a local checkout
git clone https://github.com/matanbaruch/tmdb-mcp.git
cd tmdb-mcp
npm ciThen point your client at node /absolute/path/to/tmdb-mcp/dist/index.js.
Configuration
Variable | Required | Description |
| one of these two | TMDB v3 API key, sent as the |
| one of these two | TMDB API Read Access Token, sent as a Bearer header. Used instead of the API key when both are set |
| for account tools | The server logs in on first use and keeps the session in memory |
| for account tools | An existing v3 session ID, used instead of username and password |
| no | Default response language, e.g. |
Without account credentials the catalog tools work normally, and the account tools return an error explaining what to configure.
Account access
Username and password are the simplest option. If you'd rather not store your password, create a session ID once and set TMDB_SESSION_ID:
curl -s "https://api.themoviedb.org/3/authentication/token/new?api_key=$TMDB_API_KEY"Open https://www.themoviedb.org/authenticate/<request_token> in a browser and approve it, then exchange the token:
curl -s -X POST "https://api.themoviedb.org/3/authentication/session/new?api_key=$TMDB_API_KEY" \
-H 'content-type: application/json' \
-d '{"request_token":"<request_token>"}'TMDB sessions do not expire until you revoke them under Settings → Sessions.
Images
Image fields such as poster_path, backdrop_path, still_path and profile_path are relative. Build URLs as https://image.tmdb.org/t/p/{size}{path}, with size w185, w342, w500, w780 or original. The server sends this hint to clients in its instructions.
Limitations
Lists use the TMDB v3 list API, which holds movies only. Favorites, watchlist and ratings support both movies and TV.
Episode favorites and watchlist entries do not exist on TMDB. Episodes can only be rated.
Development
npm ci
npm run typecheck
npm testnpm test builds the server, then runs:
Unit tests (
test/unit): every tool against a mocked TMDB API, checking the HTTP method, path, query, body, session handling, validation and error mapping.Stdio tests (
test/stdio): spawn the built server over stdio, negotiate both the 2026-07-28 and the 2025-11-25 protocol, and list and call tools.
Live tests
npm run test:live drives every tool against the real TMDB API through the stdio server. It covers reads and full write round trips: rate, read back, delete; favorite and watchlist on and off; and the list lifecycle. Everything it creates is cleaned up afterwards. Copy .env.example to .env and fill in an API key plus account credentials. Use a throwaway TMDB account, because the suite really writes to it.
Attribution
This product uses the TMDB API but is not endorsed or certified by TMDB.
License
Available Tools
30 toolsadd_to_listAdd a movie to a listC
Add a movie to one of my lists.
Inputs: list_id (required), movie_id (required).
clear_listClear a listADestructiveIdempotent
Remove every item from one of my lists. The list itself is kept.
Inputs: list_id (required).
create_listCreate a listA
Create a new custom list on my account. Returns the new list_id. TMDB v3 lists hold movies only.
Inputs: name (required), language, description.
delete_listDelete a listBDestructiveIdempotent
Permanently delete one of my lists.
Inputs: list_id (required).
delete_ratingDelete my ratingCDestructiveIdempotent
Remove my rating from a movie, TV show or episode.
Inputs: id (required), media_type (required), season_number, episode_number.
discover_moviesDiscover moviesARead-only
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.
Inputs: page, extra, region, sort_by, +23 more.
discover_tvDiscover TV showsBRead-only
Find TV shows by filters instead of text: genres, networks, companies, keywords, air dates, ratings, status, streaming availability.
Inputs: page, extra, sort_by, language, +24 more.
find_by_external_idFind by external IDBRead-only
Look up TMDB movies, shows, episodes or people by an external ID such as an IMDb ID (tt0111161, nm0000151) or a TVDB ID.
Inputs: external_id (required), source, language.
get_accountGet my TMDB accountBRead-only
Details of the configured TMDB account: ID, username, name, language and country.
Inputs: no named parameters.
get_account_itemsGet my favorites, watchlist or ratingsARead-only
Paged list of my favorite, watchlisted or rated movies or TV shows. media_type=episode is only valid with kind=rated.
Inputs: kind (required), media_type (required), page, sort_by, +1 more.
get_account_listsGet my listsBRead-only
The custom lists I created on TMDB, with their IDs and item counts.
Inputs: page.
get_account_statesGet my status for a titleBRead-only
Whether a movie, TV show or episode is in my favorites or watchlist, and my rating for it if I rated it.
Inputs: id (required), media_type (required), season_number, episode_number.
get_collectionGet collectionBRead-only
A movie collection (franchise) with all of its movies, e.g. the Lord of the Rings collection.
Inputs: collection_id (required), language.
get_genresGet genresARead-only
The official genre list with IDs for movies or TV, for use with discover filters.
Inputs: media_type (required), language.
get_listGet listARead-only
A TMDB list with its items. Pass movie_id to also check whether that movie is on the list.
Inputs: list_id (required), page, language, movie_id.
get_movieGet movie detailsARead-only
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.
Inputs: movie_id (required), append, language.
get_movie_listGet movie chartCRead-only
A curated movie chart: popular, top_rated, now_playing (in theaters) or upcoming.
Inputs: list (required), page, region, language.
get_personGet person detailsARead-only
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.
Inputs: person_id (required), append, language.
get_recommendationsGet recommendationsARead-only
Movies or shows related to a given one. source=recommendations uses TMDB user behaviour; source=similar uses genres and keywords.
Inputs: id (required), media_type (required), page, source, +1 more.
get_trendingGet trendingCRead-only
Trending movies, TV shows and/or people for the day or the week.
Inputs: page, language, media_type, time_window.
get_tv_episodeGet TV episodeBRead-only
Details for a single TV episode: air date, overview, guest stars, crew, rating.
Inputs: tv_id (required), season_number (required), episode_number (required), append, +1 more.
get_tv_listGet TV chartBRead-only
A curated TV chart: popular, top_rated, airing_today or on_the_air (airing in the next 7 days).
Inputs: list (required), page, language.
get_tv_seasonGet TV seasonBRead-only
Details for one season of a TV show, including its episode list.
Inputs: tv_id (required), season_number (required), append, language.
get_tv_showGet TV show detailsARead-only
Full details for a TV show: overview, seasons, networks, status, next/last episode. Use append to embed credits, videos, recommendations, content ratings and more.
Inputs: tv_id (required), append, language.
get_watch_providersGet watch providersARead-only
Where a movie or TV show can be streamed, rented or bought, per country (data from JustWatch). Pass region to get a single country.
Inputs: id (required), media_type (required), region.
rateRate a titleADestructiveIdempotent
Rate a movie, TV show or episode on my account, from 0.5 to 10 in steps of 0.5. Replaces any earlier rating.
Inputs: id (required), value (required), media_type (required), season_number, +1 more.
remove_from_listRemove a movie from a listCDestructiveIdempotent
Remove a movie from one of my lists.
Inputs: list_id (required), movie_id (required).
searchSearch TMDBARead-only
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.
Inputs: query (required), page, type, year, +2 more.
set_favoriteAdd or remove a favoriteADestructiveIdempotent
Mark a movie or TV show as a favorite (favorite=true) or remove it from favorites (favorite=false).
Inputs: media_id (required), media_type (required), favorite.
set_watchlistAdd or remove from watchlistADestructiveIdempotent
Add a movie or TV show to my watchlist (watchlist=true) or remove it (watchlist=false).
Inputs: media_id (required), media_type (required), watchlist.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Maintenance
Related MCP Connectors
Trakt MCP — TV/movie metadata + watch tracking signals
OMDb MCP — IMDB-derived movie / TV / episode data (BYO key)
Movie and series ranking as MCP tools: top titles, search, lookup by IMDb id. Free, no key.
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-
- FlicenseNot gradedqualityDmaintenanceEnables browsing movie and TV show data from TMDB and OMDB through 24 MCP tools.-
- AlicenseAqualityBmaintenanceMCP 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.23370 npm5MIT