tmdb-mcp

Local, read-only TMDB MCP server for discovering movies and TV series from Codex.

Tools

• tmdb_search_movies
• tmdb_get_movie
• tmdb_list_movies
• tmdb_trending_movies
• tmdb_discover_movies
• tmdb_get_related_movies
• tmdb_list_movie_genres
• tmdb_list_watch_providers
• tmdb_search_tv
• tmdb_get_tv_series
• tmdb_list_tv_series
• tmdb_trending_tv
• tmdb_discover_tv
• tmdb_get_related_tv
• tmdb_list_tv_genres
• tmdb_list_tv_watch_providers
• tmdb_search_people
• tmdb_get_person
• tmdb_get_person_credits
• tmdb_get_tv_season
• tmdb_get_tv_episode
• tmdb_get_collection
• tmdb_search_keywords
• tmdb_find_by_external_id
• tmdb_get_content_ratings
• tmdb_search_multi
• tmdb_search_collections
• tmdb_get_credits
• tmdb_get_reviews

The server supports title search, exact movie details, popular/top-rated/current lists, daily or weekly trends, advanced discovery filters, recommendations, similar movies, genres, and regional streaming-provider lookup.

TV tools provide the same workflows for series, including airing-today and on-the-air lists, first-air-date discovery filters, creators, aggregate cast, episode runtime, season and episode counts, and regional providers.

People tools search actors and crew, return biography details, and provide bounded movie, TV, or combined credits filtered by cast or crew roles. Movie discovery also accepts person, cast, and crew IDs for queries such as highly rated films directed by a particular filmmaker.

Additional catalog tools inspect full TV seasons and individual episodes, expand movie collections in release order, resolve TMDB entries from external IDs such as IMDb or TVDB, and return regional movie certifications or TV content ratings. Keyword search returns stable IDs accepted by the keywordIds filter in both movie and TV discovery; keywordMode controls whether multiple IDs are combined with AND or OR semantics.

Catalog tools also provide unified movie, TV, and people search; franchise search; paginated movie and TV reviews; and bounded cast or crew credits. Series and season credit requests use TMDB's aggregate view so results cover the complete run instead of only the newest season.

It does not expose account sessions, favorites, ratings, watchlists, lists, or any other mutation.

Requirements

• Node.js 22+
• pnpm
• A TMDB API Read Access Token

Setup

1. Create or sign into your TMDB account.
2. Request API access from the API section of your account settings.
3. Copy .env.example to .env.
4. Set TMDB_READ_ACCESS_TOKEN to the API Read Access Token.
5. Install and build:

pnpm install
pnpm build

Run the stable built server:

pnpm start

Example Codex configuration:

[mcp_servers.tmdb]
command = "node"
args = ["--env-file=/absolute/path/to/tmdb-mcp/.env", "/absolute/path/to/tmdb-mcp/dist/server.js"]

Use pnpm dev only while developing the server.

Tool behavior

• Language defaults to TMDB_LANGUAGE, then en-US.
• Region defaults to TMDB_REGION, then US.
• Adult content is excluded by default.
• List responses expose next_page; the server never silently crawls pages.
• Rating-sorted discovery defaults to at least 200 votes unless minVoteCount is explicitly supplied.
• Related-movie lookup defaults to TMDB recommendations. similar is the narrower genre-and-keyword alternative.
• Watch-provider results are supplied by JustWatch and include the required attribution.

Example discovery call

{
  "genres": [878],
  "releaseDateFrom": "2015-01-01",
  "minRating": 7,
  "minVoteCount": 500,
  "maxRuntime": 150,
  "sortBy": "vote_average.desc",
  "region": "US"
}

Use tmdb_list_movie_genres and tmdb_list_watch_providers to resolve the IDs accepted by discovery filters.

TV discovery uses the corresponding tmdb_list_tv_genres and tmdb_list_tv_watch_providers tools.

Resolve a person ID with tmdb_search_people, inspect their biography with tmdb_get_person, then use tmdb_get_person_credits or pass the ID through castIds, crewIds, or personIds in tmdb_discover_movies.

Resolve a discovery keyword with tmdb_search_keywords, then pass its ID to keywordIds in tmdb_discover_movies or tmdb_discover_tv.

Verification

pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm smoke

pnpm smoke makes live read-only requests and requires a configured token.

Contributing and license

See CONTRIBUTING.md for the local development workflow. This project is licensed under the MIT License.