Skip to main content
Glama

tmdb-mcp

CI

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 (initialize handshake) on the same binary.

  • 30 tools with input validation (zod) and readOnlyHint / destructiveHint / idempotentHint annotations, so clients can auto-approve reads and confirm writes.

Tools

Catalog (read-only, API key only)

Tool

What it does

search

Text search across movies, TV, people, collections, companies or keywords (type=multi by default)

get_movie

Movie details; append embeds credits, videos, images, recommendations, reviews, watch providers, release dates and more

get_tv_show

TV show details; append embeds aggregate credits, content ratings, recommendations and more

get_tv_season

One season with its episode list

get_tv_episode

One episode with guest stars and crew

get_person

Person details; append embeds movie, TV or combined credits

get_collection

A franchise and all of its movies

get_trending

Trending movies, shows or people for the day or week

get_movie_list

Popular, top rated, now playing or upcoming movies

get_tv_list

Popular, top rated, airing today or on the air TV shows

discover_movies

Filter movies by genre, cast, crew, company, keyword, dates, rating, runtime, streaming provider (any other TMDB discover parameter via extra)

discover_tv

Filter TV by genre, network, dates, status, type, rating, streaming provider

get_genres

Genre IDs for movies or TV

find_by_external_id

Look up by IMDb, TVDB, Wikidata or social IDs

get_watch_providers

Where to stream, rent or buy, for all countries or one region

get_recommendations

Recommended or similar movies and shows

Your account (needs account credentials)

Tool

Kind

What it does

get_account

read

Account ID, username, language and country

get_account_states

read

Whether a movie, show or episode is favorited, watchlisted or rated by you

get_account_items

read

Your favorites, watchlist or ratings for movies, TV or episodes

get_account_lists

read

Your custom lists

get_list

read

A list's items; pass movie_id to check membership

rate

write

Rate a movie, show or episode from 0.5 to 10

delete_rating

write

Remove a rating

set_favorite

write

Add or remove a favorite

set_watchlist

write

Add or remove a watchlist item

create_list

write

Create a list

add_to_list

write

Add a movie to a list

remove_from_list

write

Remove a movie from a list

clear_list

write

Remove every item from a list

delete_list

write

Delete a list

Related MCP server: moviefinder-mcp

Setup

1. Get TMDB credentials

  1. Create a free account at themoviedb.org.

  2. Request an API key at Settings → API. You get both an API Key and an API Read Access Token; either one works.

  3. 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-mcp

Claude 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 ci

Then point your client at node /absolute/path/to/tmdb-mcp/dist/index.js.

Configuration

Variable

Required

Description

TMDB_API_KEY

one of these two

TMDB v3 API key, sent as the api_key query parameter

TMDB_READ_ACCESS_TOKEN

one of these two

TMDB API Read Access Token, sent as a Bearer header. Used instead of the API key when both are set

TMDB_USERNAME / TMDB_PASSWORD

for account tools

The server logs in on first use and keeps the session in memory

TMDB_SESSION_ID

for account tools

An existing v3 session ID, used instead of username and password

TMDB_LANGUAGE

no

Default response language, e.g. en-US (default), fr-FR, he-IL. Every read tool also takes a language argument

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 test

npm 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

MIT

Available Tools

30 tools
add_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 listA
DestructiveIdempotent

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 listB
DestructiveIdempotent

Permanently delete one of my lists.

Inputs: list_id (required).

delete_ratingDelete my ratingC
DestructiveIdempotent

Remove my rating from a movie, TV show or episode.

Inputs: id (required), media_type (required), season_number, episode_number.

discover_moviesDiscover moviesA
Read-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 showsB
Read-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 IDB
Read-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 accountB
Read-only

Details of the configured TMDB account: ID, username, name, language and country.

Inputs: no named parameters.

get_account_itemsGet my favorites, watchlist or ratingsA
Read-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 listsB
Read-only

The custom lists I created on TMDB, with their IDs and item counts.

Inputs: page.

get_account_statesGet my status for a titleB
Read-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 collectionB
Read-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 genresA
Read-only

The official genre list with IDs for movies or TV, for use with discover filters.

Inputs: media_type (required), language.

get_listGet listA
Read-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 detailsA
Read-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 chartC
Read-only

A curated movie chart: popular, top_rated, now_playing (in theaters) or upcoming.

Inputs: list (required), page, region, language.

get_personGet person detailsA
Read-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 recommendationsA
Read-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_tv_episodeGet TV episodeB
Read-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 chartB
Read-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 seasonB
Read-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 detailsA
Read-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 providersA
Read-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 titleA
DestructiveIdempotent

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 listC
DestructiveIdempotent

Remove a movie from one of my lists.

Inputs: list_id (required), movie_id (required).

set_favoriteAdd or remove a favoriteA
DestructiveIdempotent

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 watchlistA
DestructiveIdempotent

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

    B3.4/5.0

    Scored across 30 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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_.

    Tool Count3/5

    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).

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    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
      B
      maintenance
      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.
      2
      33
      70 npm
      5
      MIT