
tmdb-mcp
io.github.Grinv/tmdb-mcp
MCP server for The Movie Database (TMDB) with IMDb/Rotten Tomatoes/Metacritic ratings via OMDb.
Documentation
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 connected, ask your agent in plain language. You need 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: the user's country, e.g. RU)"
}
}
}
}
Replace each value with your own. Only
TMDB_API_TOKENis 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 or drag it into Claude Desktop's Extensions. The bundle is
self-contained (no Node or npm needed); enter the token and the optional fields
in the install dialog. To update, download and reinstall.
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
| Tool | Purpose |
|---|---|
search_movies / search_tv / search_people | Find titles/people by name → TMDB id |
search_multi | Search movies, TV and people at once (each row has a media_type) |
get_movie / get_tv | Full details, keywords + IMDb/RT/Metacritic ratings (toggle with include_ratings) |
get_movies / get_tv_shows | Compact card(s) (title/year/genres/vote average, ratings opt-in) for 1-20 ids in one call |
get_person | Biography, department, links |
get_movie_credits / get_tv_credits | Top-billed cast and headline crew (TV: whole run, ranked by episode count) |
get_movie_recommendations / get_tv_recommendations | Recommendations from co-viewing data (what fans also liked) |
get_similar | Algorithmically similar titles (media_type + id) |
get_trending | What's popular now (movies / TV / people, day or week) |
get_movie_releases | Movies in cinemas now (now_playing) or opening soon (upcoming) in a country, with TMDB's date window |
get_movie_genres / get_tv_genres | Genre id ↔ name reference |
discover_movies | Filter by genre, date range, rating, cast/crew, companies, origin country, keywords, providers (+/-, access type), certification, regional release dates |
discover_tv | Same, plus networks/type/status and episodes airing in a date range, but no cast/crew/person or regional release-date filter (use get_person_credits for people) |
get_watch_providers | Where to stream/rent/buy, by region (JustWatch via TMDB) |
get_person_credits | A person's filmography (cast & crew) |
get_videos | Trailers/teasers/clips (YouTube links) |
get_reviews | User reviews (author, rating, text) for a movie/TV |
get_collection | A movie franchise/collection and its parts, in release order |
find_by_imdb_id | Resolve an IMDb id → TMDB movie/TV/person/episode |
get_tv_season / get_tv_episode | Season episode list / single-episode details |
search_keywords | Resolve keyword names → ids for discover_* |
search_companies | Resolve a production company name → id for discover_*'s with_companies |
search_collections | Resolve a franchise name (e.g. 'harry potter') → collection id for get_collection |
search_watch_providers | Resolve a streaming/rental service name (e.g. 'Netflix') → id for discover_*'s with_watch_providers |
get_ratings | IMDb/RT/Metacritic ratings by IMDb id or title (standalone) |
Prompts. The server also exposes two MCP prompts. recommend_similar
(title, optional media_type, optional count) plans a search for titles
similar to one the user liked, using get_similar / get_movie_recommendations /
get_tv_recommendations / discover_movies / discover_tv instead of 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. For a person's TV work it falls
back to get_person_credits, because TMDB's /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 pass the
imdb_id TMDB returns to OMDb, so ratings come back in one call. The same call
returns a free-text awards summary (major-award wins/nominations, e.g. Oscars
for a film or Emmys for a show; it covers the title as a whole, with no
attribution to individuals) and OMDb's own age rating (ratings.rated, separate
from this server's certification). Without an OMDb key the TMDB data still
works, and the ratings field reports that OMDb is unconfigured.
Localization. TMDB_LANGUAGE (e.g. ru-RU) and TMDB_REGION (e.g. RU)
are the user's default language and country: localized titles/overviews/genre
names, and the country for age ratings, cinemas and where to watch (including
discover_*'s watch filters). Tools that need them publish them as their
language/region/watch_region defaults (discover's watch_region names the
value in its description), and the agent can pass the user's own per call. search_movies/search_tv/search_multi/search_people/
search_collections, get_movie/get_tv/get_movies/get_tv_shows/get_person,
get_collection, get_movie_releases and discover_movies/discover_tv take
language.
Getting your credentials
The TMDB token is required and the OMDb key is optional. Both are free.
- 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 is sent asAuthorization: Bearer …. - OMDb key (optional). Grab a free key at
omdbapi.com/apikey.aspx (the free tier
is enough), click the activation link in the email, and set
OMDB_API_KEY. This unlocksget_ratingsand the IMDb / Rotten Tomatoes / Metacritic scores in movie and TV details. Everything else works without it.
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)
The defaults are sensible; change them only if you need to. These variables are not in Claude Desktop's install form, so CLI/Docker users set them in the environment.
| Variable | Default | Purpose |
|---|---|---|
TMDB_BASE_URL | https://api.themoviedb.org/3 | Override TMDB's API base (e.g. a proxy) |
OMDB_BASE_URL | https://www.omdbapi.com | Override OMDb's API base |
HTTP_TIMEOUT_MS | 15000 | Per-request timeout before aborting |
HTTP_RETRIES | 2 | Retries on a transient upstream failure |
TMDB_MIN_INTERVAL_MS | 60 | Minimum spacing between TMDB requests |
OMDB_MIN_INTERVAL_MS | 0 | Minimum spacing between OMDb requests |
CACHE_TTL_MS | 300000 | How long cached responses stay fresh |
CACHE_MAX_STALE_MS | 86400000 | How long past that a cached response may stand in for an unreachable upstream |
LOG_LEVEL | info | debug | info | warn | error | silent |
If TMDB/OMDb is briefly down and a tool serves a cached but expired response
instead of failing, the result carries
_meta: {"io.github.Grinv.tmdb-mcp/stale": {"age_seconds": N}} (how old the data is) alongside the normal data, so a client can
tell a degraded answer from a fresh one. "io.github.Grinv.tmdb-mcp/partial": true likewise flags a result with a part missing.
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 ≥ 22.18. Contributor/agent guidance lives in AGENTS.md.
Updating
.mcpbbundle: download the new bundle from the releases page and reinstall.- From source:
git pull && npm ci && npm run build. - npx: unpinned
npx -y tmdb-mcpfetches 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
tmdb-mcpnpm install tmdb-mcphttps://github.com/Grinv/tmdb-mcp/releases/download/v0.15.0/tmdb-mcp.mcpb# mcpb: https://github.com/Grinv/tmdb-mcp/releases/download/v0.15.0/tmdb-mcp.mcpbRelated Servers
io.github.Grinv/anilist-mcp-server
MCP server for the AniList GraphQL API — anime/manga search, details, and personal list management.
io.github.Grinv/mal-mcp
MyAnimeList MCP server: Tenrai-powered reads plus official MAL personal-list management.
io.github.Grinv/steam-games-mcp
Steam store/game data (no key) plus player profiles, libraries and achievements (Steam Web API).