{"id":"095dfbb7-0539-4ab2-b1ac-595c8bb2f977","slug":"tmdb-mcp-server","kind":"mcp","name":"tmdb-mcp-server","summary":"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.","owner":"cyanheads","repoUrl":"https://github.com/cyanheads/tmdb-mcp-server","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-06-13T06:38:30.000Z","addedAt":"2026-10-14T05:32:42.127Z","logoUrl":"https://avatars.githubusercontent.com/u/10339515?u=4c01abceabee90f9b5a4a4861cc791a239241fa3&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","databases","search"],"tags":["ai-agents","ai-tools","cyanheads","entertainment","movies","streaming","tmdb","tv"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":true,"reviewed":false,"syncedAt":"2026-10-17T15:20:58.022Z","sample":false,"url":"https://conduits.dev/tools/tmdb-mcp-server","language":"TypeScript","transports":["stdio"],"install":{"npm":"@cyanheads/tmdb-mcp-server"},"requirements":{"env":[{"name":"TMDB_API_KEY","secret":true,"required":true,"description":"TMDB v4 API Read Access Token (JWT). Sent as 'Authorization: Bearer'. Create one at https://www.themoviedb.org/settings/api."},{"name":"TMDB_LANGUAGE","secret":false,"required":false,"description":"Default response language as ISO 639-1, optionally with region (e.g. 'en-US'). Per-call language overrides it."},{"name":"TMDB_DEFAULT_REGION","secret":false,"required":false,"description":"Default ISO 3166-1 country hint (e.g. 'US') used in region-aware error messages."},{"name":"MCP_LOG_LEVEL","secret":false,"required":false,"description":"Sets the minimum log level for output (e.g., 'debug', 'info', 'warn')."}],"upstreamMayCharge":false},"tools":null,"readme":"<div align=\"center\">\n  <h1>@cyanheads/tmdb-mcp-server</h1>\n  <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>\n  <div>8 Tools • 3 Resources</div>\n  </p>\n</div>\n\n<div align=\"center\">\n\n[![Version](https://img.shields.io/badge/Version-0.1.5-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-^2.3.1-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-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.3%2B-blueviolet.svg?style=flat-square)](https://bun.sh/)\n\n</div>\n\n<div align=\"center\">\n\n[![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)\n\n[![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)\n\n</div>\n\n---\n\n## Overview\n\nMovie and TV metadata powered by The Movie Database (TMDB). Search titles and people by name, pull full credits and filmographies, discover titles by filtered criteria, track trending content, and check where to stream in your region.\n\n### Tools\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\n### Resources\n\n| Resource | Description |\n|:---|:---|\n| `tmdb://movie/{movie_id}` | Movie detail by id, as injectable context — the same enriched record as `tmdb_get_movie`. |\n| `tmdb://tv/{series_id}` | Show detail by id — the same enriched record as `tmdb_get_show`. |\n| `tmdb://person/{person_id}` | Person detail with the first 50 cast and 50 crew credits and full totals; use `tmdb_get_person` for further pages. |\n\n## Capability reference\n\n### `tmdb_search_titles` <sub>tool</sub>\n\n- `multi` mode (default) mixes movies, shows, and people, tagged with `media_type`; `movie`, `tv`, or `person` restrict to one type\n- Optional `year` (movie/tv modes), `language`, `include_adult`, and `page`; empty results return normally with recovery guidance\n- Each result carries `id`, `media_type`, title/name, `release_year`, `overview`, `vote_average`, `genre_names`, and a poster or profile URL\n\n---\n\n### `tmdb_get_movie` <sub>tool</sub>\n\n- Returns credits, videos, recommendations, similar, keywords, external ids, and release dates in one call; trim the `append` array (e.g. `[\"credits\"]`) to shrink the payload\n- Includes US certification, top-billed cast, key crew, and YouTube trailers with watch URLs\n- No streaming availability; use `tmdb_get_watch_providers`\n\n---\n\n### `tmdb_get_show` <sub>tool</sub>\n\n- Same `append` options as `tmdb_get_movie`, 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 episodes\n\n---\n\n### `tmdb_get_season` <sub>tool</sub>\n\n- Per-episode names, air dates, runtimes, vote averages, still URLs, and guest stars\n- Also returns the season's regular cast\n- `series_id` is echoed from the input; season 0 is \"Specials\"\n\n---\n\n### `tmdb_get_person` <sub>tool</sub>\n\n- Biography, vital dates, place of birth, known-for department, aliases, gender, and external ids (IMDb, Wikidata, social handles)\n- `combined_credits` split into `cast_credits` and `crew_credits`, newest first; `credits_page` (default 1) returns up to 50 of each, with full totals on every page\n- Follow `next_credits_page` for more; pages past the end return empty lists\n\n---\n\n### `tmdb_discover_titles` <sub>tool</sub>\n\n- Filter by `with_genres`/`without_genres`, `year` or a `release_date_gte`/`lte` window, `vote_average` range, `vote_count_gte`, `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) to keep low-vote titles out of the top\n- Filters that don't apply to the media type produce a notice; `with_watch_providers` without `watch_region` returns `region_required`\n\n---\n\n### `tmdb_get_trending` <sub>tool</sub>\n\n- `media_type`: `all` (default) mixes movies, shows, and people; or restrict to one type\n- `time_window`: `day` or `week` (default)\n- Up to 20 results per page, with `page` for more; empty results return normally with recovery guidance\n\n---\n\n### `tmdb_get_watch_providers` <sub>tool</sub>\n\n- Returns flatrate, rent, buy, ads, and free provider lists with logo URLs, plus the TMDB JustWatch `link`\n- `watch_region` (ISO 3166-1 alpha-2) is required; the response always states the region\n- An empty result means not streamable in that region; provider ids feed `with_watch_providers` in `tmdb_discover_titles`\n\n---\n\n### `tmdb://movie/{movie_id}` <sub>resource</sub>\n\n- Same record as `tmdb_get_movie` — `application/json`\n- `movie_id` comes from `tmdb_search_titles` or `tmdb_discover_titles`\n- Typed `movie_not_found` error when TMDB returns 404 for the id\n\n---\n\n### `tmdb://tv/{series_id}` <sub>resource</sub>\n\n- Same record as `tmdb_get_show` — `application/json`\n- `series_id` comes from `tmdb_search_titles` or `tmdb_discover_titles`\n- Typed `show_not_found` error when TMDB returns 404 for the id\n\n---\n\n### `tmdb://person/{person_id}` <sub>resource</sub>\n\n- Person detail with the first 50 cast and 50 crew credits and full totals — `application/json`; use `tmdb_get_person` for further pages\n- `person_id` comes from `tmdb_search_titles` (mode \"person\")\n- Typed `person_not_found` error when TMDB returns 404 for the id\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio and Streamable HTTP transports, pluggable auth (`none` / `jwt` / `oauth`), swappable storage (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`), structured logging with optional OpenTelemetry tracing.\n\nTMDB-specific:\n\n- Typed client for the TMDB v3 REST API, authenticated with a v4 Read Access Token\n- Image paths resolved to full image URLs; missing paths omit the field\n- Genre ids resolved to genre names, so list results are readable without an extra call\n- Detail tools return credits, videos, recommendations, keywords, and external ids in one request\n- Region-aware streaming availability backed by JustWatch; region is always an explicit input\n\nAgent-friendly output:\n\n- TMDB attribution on every response in `enrichment.attribution`\n- List responses carry total counts, page/total-pages, and a notice of the filters actually applied\n- Empty results return normally with recovery guidance, not as errors\n- Watch-provider results always state the region; capped filmographies disclose their full 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 <token>`, 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\n### Prerequisites\n\n- [Bun v1.4.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). | — |\n| `TMDB_LANGUAGE` | Default response language (e.g. `en-US`); a per-call `language` overrides it. | `en-US` |\n| `TMDB_DEFAULT_REGION` | Region shown in the missing-`watch_region` hint; never applied to queries. | `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| `LOG_TOOL_FAILURE_PAYLOADS` | Log failed tool arguments and results, redacted by key name and capped at `LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES` (default `16384`). Free-form values may contain secrets. | `false` |\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| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | OTLP log endpoint. | — |\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. |\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. |\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\n## Attribution\n\n<img src=\"https://www.themoviedb.org/assets/2/v4/logos/v2/blue_long_2-9665a76b1ae401a510ec1e0ca40ddcb3b0cfe45f1d51b77a308fea0845885648.svg\" alt=\"TMDB\" height=\"20\"> 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\n## Contributing\n\nIssues 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"}