TMDB MCP Server

What TMDB MCP Server MCP server does

TMDB MCP Server MCP server gives MCP clients access to The Movie Database for movie, TV, and person research. It can search titles and people, retrieve TMDB identifiers, and return either compact cards or detailed records. Movie and TV details can include overviews, genres, runtime or season information, ratings averages, certifications, links, and credits. Person records include biographies and links, while person credits provide cast and crew filmographies.

The server also supports discovery workflows. Agents can find movies or shows by genres, dates, ratings, vote counts, languages, companies, keywords, providers, certifications, and other filters. Movie discovery supports cast, crew, and person filters; TV discovery does not support those person-based filters, so TV work by an individual should be found through their credits. Search helpers resolve genre, keyword, company, and watch-provider names into IDs for later discovery calls.

How it works

The server communicates over MCP stdio and can be used by clients such as Claude Desktop, Cursor, and Cline. Most workflows begin with a search tool, then pass the returned TMDB ID to a detail, credit, recommendation, or media tool. Separate batch tools retrieve compact information for up to 20 movies or TV shows at once.

TMDB is the primary data source. When an IMDb ID is available and an OMDb key has been configured, detailed movie and TV lookups can add IMDb, Rotten Tomatoes, and Metacritic scores plus an awards summary. OMDb failures or missing keys return an unavailable ratings result rather than preventing the main TMDB lookup. The server also provides MCP prompts for planning similar-title searches and finding highly regarded titles associated with a person or production company.

Setup and configuration

Install the package through npm with npx -y tmdb-mcp, then add the command to the MCP client's configuration. Set TMDB_API_TOKEN to a TMDB v4 Read Access Token; this is the only required credential. OMDB_API_KEY is optional and enables external ratings enrichment. TMDB_LANGUAGE controls localization and defaults to en-US, while TMDB_REGION can set the region used for certification and related localized behavior.

Claude Desktop users can alternatively install the .mcpb bundle from a release and enter the token in the installation dialog. From source, clone the repository, run npm ci && npm run build, and start the resulting dist/index.js with Node and the same environment variables.

Tools and capabilities

TMDB MCP Server MCP server includes tools for:

• Searching movies, TV shows, people, or mixed media, including IMDb-to-TMDB ID resolution.
• Retrieving full or compact title details, certifications, ratings, reviews, collections, credits, and person filmographies.
• Finding recommendations, genre- or keyword-based similar titles, trending media, trailers, teasers, and clips.
• Discovering movies and TV shows with structured filters such as dates, ratings, providers, companies, networks, status, and certification.
• Checking streaming, rental, and purchase availability by country through TMDB's JustWatch data.
• Reading TV season episode lists and individual episode details, including episode directors and writers.

Limitations and notes

Regional behavior varies by tool. get_watch_providers is the appropriate choice for availability by country, while a movie search region mainly selects the release date displayed in results. Certifications fall back from the requested region to the US and then another available country; the response identifies which region supplied the value.

TV discovery cannot filter by cast, crew, or person. TV show-level credits also may not reliably identify creators, writers, or directors, so use get_tv.created_by for show creators and get_tv_episode for episode-level writing and directing information. Similar-title result counts reflect TMDB's unfiltered totals even when the server removes weak broad-genre matches, so pages may contain few or no usable results. Video results are limited by the configured TMDB_LANGUAGE and have no per-call language override.