TMDB MCP Server
# TMDB MCP Server
[](https://www.npmjs.com/package/tmdb-mcp)
[](https://github.com/Grinv/tmdb-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.Grinv/tmdb-mcp&version=latest)
[](https://glama.ai/mcp/servers/Grinv/tmdb-mcp)
An [MCP](https://modelcontextprotocol.io) server for **The Movie Database
(TMDB)**: search and look up movies, TV shows and people, and read
**IMDb / Rotten Tomatoes / Metacritic** ratings (via [OMDb](https://www.omdbapi.com/))
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](#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):**
```json
{
"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_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](https://github.com/Grinv/tmdb-mcp/releases/latest),
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](https://github.com/Grinv/tmdb-mcp/blob/main/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.
1. **TMDB token (required).** Create a free account at
[themoviedb.org](https://www.themoviedb.org/signup), then open
**[Settings → API](https://www.themoviedb.org/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 as `Authorization: Bearer …`.
2. **OMDb key (optional).** Grab a free key at
**[omdbapi.com/apikey.aspx](https://www.omdbapi.com/apikey.aspx)** (the free tier
is enough), 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. Everything else works without it.
Put these in your MCP client config's `env` block (see
[docs/clients.md](https://github.com/Grinv/tmdb-mcp/blob/main/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
```sh
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](https://github.com/Grinv/tmdb-mcp/blob/main/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](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](SECURITY.md) for the full breakdown and how to report a
vulnerability.
## License
[MIT](LICENSE) © Grinv
TDQS
Scored across 33 tools
Most tools have a clearly distinct role, and the descriptions explicitly disambiguate the risky pairs (search_movies vs search_multi, get_movie vs get_movies, get_movie_recommendations vs get_similar, get_movie_releases vs discover_movies vs get_trending). The remaining hazard is naming-level: singular/plural pairs like get_movie/get_movies and get_tv/get_tv_shows look interchangeable at a glance even though the descriptions define one as full detail and the other as a batch card.
The surface follows a predictable verb_noun scheme (get_movie, search_tv, discover_movies, get_tv_episode, get_watch_providers), which makes the set easy to scan. Minor deviations exist: find_by_imdb_id uses 'find' instead of get/search, and get_similar/get_trending omit the noun.
33 tools is heavy and sits in the 'too many' band, but the TMDB domain is genuinely broad (movies, TV, seasons, episodes, people, credits, collections, providers, genres, keywords, ratings, discovery), so nearly every tool maps to a real capability rather than filler. It is still borderline: a few batch/detail pairs (get_movie vs get_movies, get_tv vs get_tv_shows) and the four search_* tools could arguably be consolidated.
Coverage is exceptional: search across all media types, full detail plus compact batch cards, credits for movies/TV/people, recommendations and similar, reviews, collections, trending, two rich discover endpoints, watch providers, videos, seasons and episodes, plus external ratings, genre/keyword/company/provider resolution and IMDb-id resolution. Only minor read paths are absent (images/posters, company/network detail endpoints, account lists), which agents can work around.