{
"markdown": "\n
@cyanheads/tmdb-mcp-server
\n
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.\n
8 Tools • 3 Resources
\n \n
\n\n[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/tmdb-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/tmdb-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)\n\n
\n\n\n\n[](https://github.com/cyanheads/tmdb-mcp-server/releases/latest/download/tmdb-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=tmdb-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvdG1kYi1tY3Atc2VydmVyIl0sImVudiI6eyJUTURCX0FQSV9LRVkiOiJ5b3VyLXRtZGItcmVhZC1hY2Nlc3MtdG9rZW4ifX0=) [](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)\n\n[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)\n\n
\n\n---\n\n## Tools\n\nEight 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.\n\n| Tool | Description |\n|:---|:---|\n| `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. |\n| `tmdb_get_movie` | Full movie detail in one call — synopsis, runtime, genres, US certification, budget/revenue, cast, crew, trailers, recommendations, keywords, external ids. |\n| `tmdb_get_show` | Full TV show detail — overview, air dates, status, season/episode counts, creators, networks, season summaries, cast, trailers, content rating. |\n| `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. |\n| `tmdb_get_person` | Person detail and full filmography — biography, vital dates, the `combined_credits` cast/crew lists, and cross-platform external ids. |\n| `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. |\n| `tmdb_get_trending` | Trending movies, TV, or people for the day or week. |\n| `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. |\n\nAll 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.\n\n### `tmdb_search_titles`\n\nResolve a movie, show, or person name to ranked results with integer ids.\n\n- `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\n- Optional `year` filter (movie/tv modes), `language` override, `include_adult` toggle, and `page` for paging past the first 20\n- Each result carries `id`, `media_type`, title/name, `release_year`, `overview`, `vote_average`, resolved `genre_names`, and the relevant poster/profile URL\n- An empty result set is a valid answer, returned with recovery guidance — not an error\n\n---\n\n### `tmdb_get_movie`\n\nFetch full movie detail by TMDB id in a single request.\n\n- 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)\n- US theatrical certification extracted from the `release_dates` namespace; top-billed cast and key crew (Director/Writer/Screenplay/Producer); YouTube trailers with watch URLs\n- Does not include streaming availability — that is region-specific; use `tmdb_get_watch_providers`\n\n---\n\n### `tmdb_get_show`\n\nFetch full TV show detail by series id — the series mirror of `tmdb_get_movie`.\n\n- Same `append_to_response` set, with `content_ratings` (US TV rating) in place of `release_dates`\n- Adds season summaries, creators, networks, and the last/next episode to air\n- Pass a `season_number` from `seasons[]` to `tmdb_get_season` for the episode list\n\n---\n\n### `tmdb_get_season`\n\nFetch the episode list for one season of a show — bridges the show-level summary and per-episode detail.\n\n- Per-episode names, air dates, runtimes, vote averages, still URLs, and guest stars (embedded per episode)\n- Plus the season's regular recurring cast (distinct from per-episode guest stars)\n- `series_id` is echoed from the input — the TMDB season endpoint does not return it. Season 0 is \"Specials\"\n\n---\n\n### `tmdb_get_person`\n\nFetch person detail and the full combined filmography.\n\n- Biography, birth/death dates, place of birth, known-for department, aliases, gender label\n- `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\n- IMDb id plus the extended cross-platform id set (Wikidata, social handles) for chaining to other servers\n\n---\n\n### `tmdb_discover_titles`\n\nThe power-query — filtered, sorted discovery across movies or TV.\n\n- 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\n- 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\n- `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\n- `with_watch_providers` requires a `watch_region` — streaming availability is region-specific. Omitting the region returns a typed `region_required` error\n\n---\n\n### `tmdb_get_watch_providers`\n\nFind where a movie or TV title streams in one region.\n\n- 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\n- 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\n- An empty result for a region is a valid \"not available to stream here\" answer, not an error\n- Provider ids in the result feed back into `tmdb_discover_titles` `with_watch_providers`\n\n## Resources\n\n| Type | Name | Description |\n|:---|:---|:---|\n| Resource | `tmdb://movie/{movie_id}` | Movie detail by id, as injectable context — the same enriched record as `tmdb_get_movie`. |\n| Resource | `tmdb://tv/{series_id}` | Show detail by id — the same enriched record as `tmdb_get_show`. |\n| Resource | `tmdb://person/{person_id}` | Person detail and filmography by id — the same record as `tmdb_get_person`. |\n\nAll 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.\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):\n\n- Declarative tool and resource definitions — single file per primitive, framework handles registration and validation\n- Unified error handling — handlers throw, framework catches, classifies, and formats\n- Typed error contracts — every tool declares its failure reasons with recovery guidance for the agent\n- Pluggable auth: `none`, `jwt`, `oauth`\n- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`\n- Structured logging with optional OpenTelemetry tracing\n- STDIO and Streamable HTTP transports — runs locally or on Cloudflare Workers from the same codebase\n\nTMDB-specific:\n\n- Single typed client for the TMDB v3 REST API, authenticated with a v4 Read Access Token over `Authorization: Bearer`\n- Image `*_path` fields resolved to full `https://image.tmdb.org/t/p/{size}{path}` URLs — null paths omit the field rather than emitting a broken URL\n- `genre_ids[]` resolved to genre names from per-`media_type` maps cached at startup, so list results carry readable genres without an extra call\n- Detail tools collapse credits, videos, recommendations, similar, keywords, and external ids into one HTTP call via `append_to_response`\n- Region-aware streaming availability backed by JustWatch — region is always an explicit input, never assumed\n\nAgent-friendly output:\n\n- TMDB attribution on every response — surfaced in `enrichment.attribution` so it reaches both the `structuredContent` and `content[]` client surfaces\n- Provenance and pagination on list responses — total-result counts, page/total-pages, and an effective-filter notice so agents can reason about what was actually queried\n- Empty results and empty provider regions return normally with recovery guidance, not as errors — \"no titles matched\" and \"not streamable here\" are real answers an agent must act on\n- Region and truncation caveats are explicit — watch-provider results always state the region; capped filmographies disclose the pre-cap totals\n\n## Getting started\n\nA TMDB API Read Access Token is required. Create a free TMDB account, then copy the **API Read Access Token** (a v4 JWT) from your [API settings](https://www.themoviedb.org/settings/api) — this server authenticates v3 endpoints with `Authorization: Bearer `, not the legacy `?api_key=` query parameter.\n\nAdd the following to your MCP client configuration file.\n\n```json\n{\n \"mcpServers\": {\n \"tmdb-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"bunx\",\n \"args\": [\"@cyanheads/tmdb-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\",\n \"TMDB_API_KEY\": \"your-tmdb-read-access-token\"\n }\n }\n }\n}\n```\n\nOr with npx (no Bun required):\n\n```json\n{\n \"mcpServers\": {\n \"tmdb-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cyanheads/tmdb-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\",\n \"TMDB_API_KEY\": \"your-tmdb-read-access-token\"\n }\n }\n }\n}\n```\n\nOr with Docker:\n\n```json\n{\n \"mcpServers\": {\n \"tmdb-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"-i\", \"--rm\",\n \"-e\", \"MCP_TRANSPORT_TYPE=stdio\",\n \"-e\", \"TMDB_API_KEY=your-tmdb-read-access-token\",\n \"ghcr.io/cyanheads/tmdb-mcp-server:latest\"\n ]\n }\n }\n}\n```\n\nFor Streamable HTTP, set the transport and start the server:\n\n```sh\nMCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 TMDB_API_KEY=... bun run start:http\n# Server listens at http://localhost:3010/mcp\n```\n\nRefer to \"your MCP client configuration file\" generically — different clients use different config paths, and this server isn't client-specific.\n\n### Prerequisites\n\n- [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+).\n- A TMDB **API Read Access Token** (v4 JWT) — free from your [TMDB API settings](https://www.themoviedb.org/settings/api).\n\n### Installation\n\n1. **Clone the repository:**\n\n```sh\ngit clone https://github.com/cyanheads/tmdb-mcp-server.git\n```\n\n2. **Navigate into the directory:**\n\n```sh\ncd tmdb-mcp-server\n```\n\n3. **Install dependencies:**\n\n```sh\nbun install\n```\n\n4. **Configure environment:**\n\n```sh\ncp .env.example .env\n# edit .env and set TMDB_API_KEY\n```\n\n## Configuration\n\nAll configuration is validated at startup via Zod schemas. Key environment variables:\n\n| Variable | Description | Default |\n|:---|:---|:---|\n| `TMDB_API_KEY` | **Required.** TMDB v4 API Read Access Token (JWT), sent as `Authorization: Bearer`. Not the v3 `?api_key=` value. | — |\n| `TMDB_LANGUAGE` | Default response language as ISO 639-1, optionally with region (e.g. `en-US`). A per-call `language` input overrides it. | `en-US` |\n| `TMDB_DEFAULT_REGION` | Default ISO 3166-1 country hint used in region-aware error messages. `tmdb_get_watch_providers` still requires an explicit `watch_region`. | `US` |\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |\n| `MCP_HTTP_PORT` | Port for the HTTP server. | `3010` |\n| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |\n| `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |\n| `STORAGE_PROVIDER_TYPE` | Storage backend. | `in-memory` |\n| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry) (spans, metrics, completion logs). | `false` |\n\nSee [`.env.example`](./.env.example) for the full list of optional overrides.\n\n## Running the server\n\n### Local development\n\n- **Build and run:**\n\n ```sh\n # One-time build\n bun run rebuild\n\n # Run the built server\n bun run start:stdio\n # or\n bun run start:http\n ```\n\n- **Run checks and tests:**\n\n ```sh\n bun run devcheck # Lint, format, typecheck, security\n bun run test # Vitest test suite\n bun run lint:mcp # Validate MCP definitions against spec\n ```\n\n### Docker\n\n```sh\ndocker build -t tmdb-mcp-server .\ndocker run --rm -e TMDB_API_KEY=your-token -p 3010:3010 tmdb-mcp-server\n```\n\nThe Dockerfile defaults to HTTP transport, stateless session mode, and logs to `/var/log/tmdb-mcp-server`. OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.\n\n## Project structure\n\n| Directory | Purpose |\n|:---|:---|\n| `src/index.ts` | `createApp()` entry point — registers tools and resources, and primes the startup cache in `setup()`. |\n| `src/config` | Server-specific environment variable parsing and validation with Zod. |\n| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`) — the eight TMDB tools. |\n| `src/mcp-server/resources` | Resource definitions (`*.resource.ts`) — movie, TV, and person detail. |\n| `src/services/tmdb` | TMDB v3 REST client — Bearer auth, retry/timeout, the image/genre startup cache, and the `imageUrl`/`genreNames` helpers. |\n| `tests/` | Unit and integration tests mirroring `src/`. |\n\n## Development guide\n\nSee [`AGENTS.md`](./AGENTS.md) (or [`CLAUDE.md`](./CLAUDE.md), the same content) for development guidelines and architectural rules. The short version:\n\n- Handlers throw, framework catches — no `try/catch` in tool logic\n- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage\n- Register new tools and resources via the barrels in `src/mcp-server/*/definitions/index.ts`\n- Wrap the TMDB API: validate raw → normalize to the domain type → return the output schema; never fabricate missing fields (null poster paths omit the URL, unknown genre ids are dropped)\n\n## Contributing\n\nIssues and pull requests are welcome. Run checks and tests before submitting:\n\n```sh\nbun run devcheck\nbun run test\n```\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE) for details.\n\n---\n\n![\"TMDB\"](\"https://www.themoviedb.org/assets/2/v4/logos/v2/blue_long_2-9665a76b1ae401a510ec1e0ca40ddcb3b0cfe45f1d51b77a308fea0845885648.svg\")
This product uses the TMDB API but is not endorsed or certified by TMDB. Streaming availability data is provided by JustWatch via TMDB and is region-specific.\n",
"bytes": 17187,
"sha": "886c75499f2eaa3f1f1042a7c46c37ffce247a7ec0bf6d36b83f99a565160d96",
"repo_slug": "cyanheads/tmdb-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_cyanheads_tmdb_mcp_server_7df77b03/readme"
}