tmdb-mcp-server

<div align="center">
  <h1>@cyanheads/tmdb-mcp-server</h1>
  <p><b>Search movies, TV, and people on The Movie Database (TMDB) — credits, ratings, trailers, images, recommendations, and region-aware streaming availability via MCP. STDIO or Streamable HTTP.</b>
  <div>8 Tools • 3 Resources</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.1.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/tmdb-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/tmdb-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/tmdb-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.2-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/tmdb-mcp-server/releases/latest/download/tmdb-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=tmdb-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvdG1kYi1tY3Atc2VydmVyIl0sImVudiI6eyJUTURCX0FQSV9LRVkiOiJ5b3VyLXRtZGItcmVhZC1hY2Nlc3MtdG9rZW4ifX0=) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22tmdb-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Ftmdb-mcp-server%22%5D%2C%22env%22%3A%7B%22TMDB_API_KEY%22%3A%22your-tmdb-read-access-token%22%7D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

---

## Tools

Eight tools organized search-before-detail — `tmdb_search_titles` resolves a name to an integer id, the `get_*` tools fetch full records, and `tmdb_discover_titles` / `tmdb_get_trending` / `tmdb_get_watch_providers` cover filtered browsing and streaming availability. TMDB keys on integer ids, not titles, so search comes first.

| Tool | Description |
|:---|:---|
| `tmdb_search_titles` | Search movies, TV, and people by name. The required first step — resolves a name to the integer id the detail tools consume. |
| `tmdb_get_movie` | Full movie detail in one call — synopsis, runtime, genres, US certification, budget/revenue, cast, crew, trailers, recommendations, keywords, external ids. |
| `tmdb_get_show` | Full TV show detail — overview, air dates, status, season/episode counts, creators, networks, season summaries, cast, trailers, content rating. |
| `tmdb_get_season` | Episode list for one season — names, air dates, runtimes, vote averages, stills, per-episode guest stars, plus the season's regular cast. |
| `tmdb_get_person` | Person detail and full filmography — biography, vital dates, the `combined_credits` cast/crew lists, and cross-platform external ids. |
| `tmdb_discover_titles` | Filtered, sorted discovery across movies or TV — the power-query: genre, date/vote ranges, vote-count floor, cast/crew/network, watch providers, runtime, sort. |
| `tmdb_get_trending` | Trending movies, TV, or people for the day or week. |
| `tmdb_get_watch_providers` | Region-scoped streaming availability (JustWatch) — flatrate/rent/buy/ads/free provider lists plus the TMDB link. A region code is required. |

All list and detail responses resolve image `*_path` fields to full `https://image.tmdb.org/t/p/…` URLs and resolve `genre_ids[]` to genre names. Every tool carries the TMDB attribution in its output enrichment.

### `tmdb_search_titles`

Resolve a movie, show, or person name to ranked results with integer ids.

- `multi` mode (default) mixes movies, shows, and people, each result tagged with `media_type`; `movie`/`tv`/`person` restrict to one type and enable type-specific ranking
- Optional `year` filter (movie/tv modes), `language` override, `include_adult` toggle, and `page` for paging past the first 20
- Each result carries `id`, `media_type`, title/name, `release_year`, `overview`, `vote_average`, resolved `genre_names`, and the relevant poster/profile URL
- An empty result set is a valid answer, returned with recovery guidance — not an error

---

### `tmdb_get_movie`

Fetch full movie detail by TMDB id in a single request.

- Folds credits, videos, recommendations, similar, keywords, external ids, and release dates into one call via `append_to_response` — trim the `append` array to shrink the payload (e.g. `["credits"]` for cast only)
- US theatrical certification extracted from the `release_dates` namespace; top-billed cast and key crew (Director/Writer/Screenplay/Producer); YouTube trailers with watch URLs
- Does not include streaming availability — that is region-specific; use `tmdb_get_watch_providers`

---

### `tmdb_get_show`

Fetch full TV show detail by series id — the series mirror of `tmdb_get_movie`.

- Same `append_to_response` set, with `content_ratings` (US TV rating) in place of `release_dates`
- Adds season summaries, creators, networks, and the last/next episode to air
- Pass a `season_number` from `seasons[]` to `tmdb_get_season` for the episode list

---

### `tmdb_get_season`

Fetch the episode list for one season of a show — bridges the show-level summary and per-episode detail.

- Per-episode names, air dates, runtimes, vote averages, still URLs, and guest stars (embedded per episode)
- Plus the season's regular recurring cast (distinct from per-episode guest stars)
- `series_id` is echoed from the input — the TMDB season endpoint does not return it. Season 0 is "Specials"

---

### `tmdb_get_person`

Fetch person detail and the full combined filmography.

- Biography, birth/death dates, place of birth, known-for department, aliases, gender label
- `combined_credits` split into `cast_credits` and `crew_credits`, recency-ordered (most recent first) and capped to a display size — the pre-cap totals are reported and truncation is disclosed in the enrichment
- IMDb id plus the extended cross-platform id set (Wikidata, social handles) for chaining to other servers

---

### `tmdb_discover_titles`

The power-query — filtered, sorted discovery across movies or TV.

- Filter by `with_genres`/`without_genres`, exact `year` or a `release_date_gte`/`lte` window, `vote_average` range, `vote_count_gte` floor, `with_cast`/`with_crew` (movie), `with_networks` (tv), `with_watch_providers` + `watch_region`, `with_original_language`, and `runtime` range
- Sort by popularity, revenue, vote average, vote count, or release date. Pair `vote_average.desc` with `vote_count_gte` (~100–1000) so a 10.0-from-3-votes title does not dominate
- `with_cast`/`with_crew` are movie-only and `with_networks` is tv-only on TMDB; the tool accepts them for both `media_type` values and no-ops the inapplicable ones with a notice
- `with_watch_providers` requires a `watch_region` — streaming availability is region-specific. Omitting the region returns a typed `region_required` error

---

### `tmdb_get_watch_providers`

Find where a movie or TV title streams in one region.

- Returns flatrate (subscription), rent, buy, ads (ad-supported free), and free provider lists with logo URLs, plus the TMDB JustWatch-backed `link` — the supported path to actual deep links
- A `watch_region` (ISO 3166-1 alpha-2) is required: availability is region-specific and there is no global answer; the response always carries a region caveat
- An empty result for a region is a valid "not available to stream here" answer, not an error
- Provider ids in the result feed back into `tmdb_discover_titles` `with_watch_providers`

## Resources

| Type | Name | Description |
|:---|:---|:---|
| Resource | `tmdb://movie/{movie_id}` | Movie detail by id, as injectable context — the same enriched record as `tmdb_get_movie`. |
| Resource | `tmdb://tv/{series_id}` | Show detail by id — the same enriched record as `tmdb_get_show`. |
| Resource | `tmdb://person/{person_id}` | Person detail and filmography by id — the same record as `tmdb_get_person`. |

All resource data is also reachable via tools — the three resources are convenience wrappers over the detail service methods, so tool-only clients lose nothing. Search, discovery, trending, and seasons are query paths or intermediate records, not addressable entities, so they have no resources. There are no prompts: this is a data/lookup server with no recurring multi-step interaction template.

## Features

Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):

- Declarative tool and resource definitions — single file per primitive, framework handles registration and validation
- Unified error handling — handlers throw, framework catches, classifies, and formats
- Typed error contracts — every tool declares its failure reasons with recovery guidance for the agent
- Pluggable auth: `none`, `jwt`, `oauth`
- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`
- Structured logging with optional OpenTelemetry tracing
- STDIO and Streamable HTTP transports — runs locally or on Cloudflare Workers from the same codebase

TMDB-specific:

- Single typed client for the TMDB v3 REST API, authenticated with a v4 Read Access Token over `Authorization: Bearer`
- Image `*_path` fields resolved to full `https://image.tmdb.