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.

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

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:

• 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: