TMDB MCP Server

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

The server speaks standard MCP over stdio, so it works with any MCP client
(Claude Desktop/Code, Cursor, VS Code, Cline, …).

Once it's connected, just ask your agent in natural language (needs a free TMDB
token; see Getting your credentials):

"Search for the movie Dune: Part Two and show its overview, genres and runtime."
"What movies are trending this week?"
"Find TV shows similar to Breaking Bad."
"Who directed Oppenheimer? Show the main cast."
"What's Greta Gerwig's filmography?"
"Discover highly-rated sci-fi movies from the 2010s, sorted by rating."
"Where can I stream The Bear in the US?"
"Show me the trailer for Deadpool & Wolverine."
"List the episodes of Severance season 1."
"Which movie has IMDb id tt0111161?"
"Search for people named Zendaya."
"Get the year, genres and rating for these five movies in one go: Dune, Dune: Part Two, Arrival, Sicario and Blade Runner 2049."
"What are the best limited series to binge over a weekend?"
"What TV shows can I watch with my 9-year-old kid?"
"What movies has A24 produced?"
"What are Tarantino's best-rated crime movies?"
"Who composed the music for My Neighbor Totoro, and what else has he scored?"

With an optional (free) OMDb key, ratings are added too:

"What are the IMDb, Rotten Tomatoes and Metacritic scores for The Godfather?"
"Compare the critics' scores for Barbie and Oppenheimer."

Install

Add it to your MCP client's config. The only required credential is a TMDB v4
Read Access Token; OMDB_API_KEY (ratings) and TMDB_LANGUAGE / TMDB_REGION
(localization) are optional.

Via npx (no install):

{
  "mcpServers": {
    "tmdb": {
      "command": "npx",
      "args": ["-y", "tmdb-mcp"],
      "env": {
        "TMDB_API_TOKEN": "your-tmdb-v4-read-access-token (required)",
        "OMDB_API_KEY": "your-omdb-key (optional: IMDb/RT/Metacritic ratings)",
        "TMDB_LANGUAGE": "en-US (optional: localize, e.g. ru-RU)",
        "TMDB_REGION": "US (optional: region for certifications, e.g. RU)"
      }
    }
  }
}

Replace each value with your own. Only TMDB_API_TOKEN is required; delete the
lines marked optional if you don't need them.

As a .mcpb bundle (easiest for Claude Desktop): download tmdb-mcp.mcpb
from the latest release,
then open it / drag it into Claude Desktop's Extensions. It's a self-contained
bundle (no Node or npm needed); enter the token and the optional fields in the
install dialog. Re-download and reinstall to update.

From source: git clone, then npm ci && npm run build, and point the client
at it with "command": "node", "args": ["/ABS/PATH/tmdb-mcp/dist/index.js"] and
the same env as above.

See docs/clients.md for per-client details and all tunables.

What it does

Prompts. Alongside the tools above, the server exposes two MCP prompts:
recommend_similar (title, optional media_type, optional count) plans a
search for titles similar to one the user liked, driving get_similar /
get_movie_recommendations / get_tv_recommendations / discover_movies /
discover_tv instead of relying on the model's own knowledge. top_by_entity
(name, optional entity_type, genre, media_type, count) finds the
best-regarded titles from a person or a production company/studio (e.g. "A24's
top movies" or "Tarantino's best crime films") via discover_movies/
discover_tv, and for a person's TV work specifically falls back to
get_person_credits (TMDB's own /discover/tv can't filter by person at all).

Backbone vs. enrichment. TMDB is the primary source (search, metadata,
people, trending). OMDb is optional enrichment: get_movie/get_tv chain the
imdb_id TMDB returns into an OMDb lookup, so ratings come back in one call,
along with a free-text awards summary (major-award wins/nominations, e.g. Oscars
for a film or Emmys for a show, for the title as a whole, not attributed to any
one person) and OMDb's own age rating (ratings.rated, separate from this
server's own certification). Without an OMDb key the TMDB data still works;
the ratings field just reports that it is unconfigured.

Localization. Set TMDB_LANGUAGE (e.g. ru-RU) and TMDB_REGION (e.g.
RU) to get localized titles/overviews/genre names and region-specific
certifications. The search tools, get_movie/get_tv/get_person,
get_collection and discover_movies/discover_tv also accept a per-call
language override.

Getting your credentials

One token is required (TMDB); the OMDb key is optional. Both are free.

1. TMDB token (required). Create a free account at
   themoviedb.org, then open
   Settings → API and request an API
   key (personal use). Copy the "API Read Access Token" (the long v4 token, not
   the short v3 key) into TMDB_API_TOKEN. It's sent as Authorization: Bearer ….
2. OMDb key (optional). Grab a free key at
   omdbapi.com/apikey.aspx (the free tier
   is fine), click the activation link in the email, and set OMDB_API_KEY. This
   unlocks get_ratings and the IMDb / Rotten Tomatoes / Metacritic scores in movie
   and TV details. Without it, everything else still works.

Put these in your MCP client config's env block (see
docs/clients.md for per-client snippets). Never commit them.
TMDB_LANGUAGE / TMDB_REGION optionally set default locale/region (e.g. ru-RU, RU).

Advanced tuning (env-only, no install-UI equivalent)

Sensible defaults; only set these if you know you need to. Env var only, not
exposed in Claude Desktop's install form, so CLI/Docker users set them directly.

If TMDB/OMDb is briefly down and a tool falls back to a cached-but-expired
response rather than failing, the result carries
_meta: {"tmdb-mcp/stale": true} alongside the normal data, so a client can
tell a degraded answer from a fresh one.

Develop

npm install
npm run build        # type-check + bundle to dist/index.js
npm test             # node:test (mocked, offline)
npm run lint
npm run format
npm run check:api    # live upstream health-check (needs the env credentials)
npm run inspector    # run under the MCP Inspector

Runtime requires Node ≥ 20.11. Contributor/agent guidance lives in
AGENTS.md.

Updating

• .mcpb bundle: download the new bundle from the releases page and reinstall.
• From source: git pull && npm ci && npm run build.
• npx: unpinned npx -y tmdb-mcp fetches the latest on the next run.

This product uses the TMDB API but is not endorsed or certified by TMDB.

Privacy Policy

tmdb-mcp runs entirely on your own machine and collects no data of its own.
See PRIVACY.md for exactly what it sends to TMDB/OMDb and what
(if anything) it stores locally.

Security

Read-only, two fixed upstream hosts, credentials never persisted. See
SECURITY.md for the full breakdown and how to report a
vulnerability.

License

MIT © Grinv