tmdb-mcp-server
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.
Install / Use
claude mcp add cyanheads -- npx -y github:cyanheads/tmdb-mcp-serverIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
Data & AnalyticsSupported Platforms
Our assessment of tmdb-mcp-server
tmdb-mcp-server scores 83/100 on our quality scale, 484th of 604 Data & Analytics skills we index.
Its MCP Server is 14 KB long, well organised into 27 sections with 5 code examples: a thorough specification that gives an agent plenty to work with.
It has 3 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated 17 days ago, so tmdb-mcp-server is actively maintained.
- It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 92/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-11-15. Automated pattern scan on 2026-11-15. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
tmdb-mcp-server compared with similar skills
All 4 of these similar skills score higher than tmdb-mcp-server; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| tmdb-mcp-server (this skill)by cyanheads | 83 | 3 | 17d ago | MCP Server |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
Frequently asked questions
- How do I install tmdb-mcp-server?
- Run
claude mcp add cyanheads -- npx -y github:cyanheads/tmdb-mcp-server. The install tabs above show the steps for each supported agent. - Which AI agents does tmdb-mcp-server work with?
- It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
- Is tmdb-mcp-server safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is Apache-2.0-licensed and scores 92/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is tmdb-mcp-server still maintained?
- The repository was last updated 17 days ago, so tmdb-mcp-server is actively maintained.
Skill content
View source on GitHubOverview
Movie 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.
Tools
| 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. |
Resources
| Resource | Description |
|:---|:---|
| tmdb://movie/{movie_id} | Movie detail by id, as injectable context — the same enriched record as tmdb_get_movie. |
| tmdb://tv/{series_id} | Show detail by id — the same enriched record as tmdb_get_show. |
| 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. |
| skill://tmdb-guide/SKILL.md | Agent guide for regional watchlists, directing credits, filmography paging, and season traversal. |
Capability reference
tmdb_search_titles <sub>tool</sub>
multimode (default) mixes movies, shows, and people, tagged withmedia_type;movie,tv, orpersonrestrict to one type- Optional
year(movie/tv modes),language,include_adult, andpage; empty results return normally with recovery guidance - Each result carries
id,media_type, title/name,release_year,overview,vote_average,genre_names, and a poster or profile URL
tmdb_get_movie <sub>tool</sub>
- Returns credits, videos, recommendations, similar, keywords, external ids, and release dates in one call; trim the
appendarray (e.g.["credits"]) to shrink the payload - Includes US certification, top-billed cast, key crew, and YouTube trailers with watch URLs
- No streaming availability; use
tmdb_get_watch_providers
tmdb_get_show <sub>tool</sub>
- Same
appendoptions astmdb_get_movie, withcontent_ratings(US TV rating) in place ofrelease_dates - Adds season summaries, creators, networks, and the last/next episode to air
- Pass a
season_numberfromseasons[]totmdb_get_seasonfor episodes
tmdb_get_season <sub>tool</sub>
- Per-episode names, air dates, runtimes, vote averages, still URLs, and guest stars
- Also returns the season's regular cast
series_idis echoed from the input; season 0 is "Specials"
tmdb_get_person <sub>tool</sub>
- Biography, vital dates, place of birth, known-for department, aliases, gender, and external ids (IMDb, Wikidata, social handles)
combined_creditssplit intocast_creditsandcrew_credits, newest first;credits_page(default 1) returns up to 50 of each, with full totals on every page- Follow
next_credits_pagefor more; pages past the end return empty lists
tmdb_discover_titles <sub>tool</sub>
- Filter by
with_genres/without_genres,yearor arelease_date_gte/ltewindow,vote_averagerange,vote_count_gte,with_cast/with_crew(movie),with_networks(tv),with_watch_providers+watch_region,with_original_language, andruntimerange - Sort by popularity, revenue, vote average, vote count, or release date; pair
vote_average.descwithvote_count_gte(~100–1000) to keep low-vote titles out of the top - Filters that don't apply to the media type produce a notice;
with_watch_providerswithoutwatch_regionreturnsregion_required
tmdb_get_trending <sub>tool</sub>
media_type:all(default) mixes movies, shows, and people; or restrict to one typetime_window:dayorweek(default)- Up to 20 results per page, with
pagefor more; empty results return normally with recovery guidance
tmdb_get_watch_providers <sub>tool</sub>
- Returns flatrate, rent, buy, ads, and free provider lists with logo URLs, plus the TMDB JustWatch
link watch_region(ISO 3166-1 alpha-2) is required; the response always states the region- An empty result means not streamable in that region; provider ids feed
with_watch_providersintmdb_discover_titles
tmdb://movie/{movie_id} <sub>resource</sub>
- Same record as
tmdb_get_movie—application/json movie_idcomes fromtmdb_search_titlesortmdb_discover_titles- Typed
movie_not_founderror when TMDB returns 404 for the id
tmdb://tv/{series_id} <sub>resource</sub>
- Same record as
tmdb_get_show—application/json series_idcomes fromtmdb_search_titlesortmdb_discover_titles- Typed
show_not_founderror when TMDB returns 404 for the id
tmdb://person/{person_id} <sub>resource</sub>
- Person detail with the first 50 cast and 50 crew credits and full totals —
application/json; usetmdb_get_personfor further pages person_idcomes fromtmdb_search_titles(mode "person")- Typed
person_not_founderror when TMDB returns 404 for the id
skill://tmdb-guide/SKILL.md <sub>resource</sub>
- The
tmdb-guideskill covers identifier sources, regional provider categories, directing-credit verification, and multi-step research gates - Available through MCP skill discovery and resource reads; included in plugin installs, npm, Docker, and MCPB bundles
Features
Built on @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.
TMDB-specific:
- Typed client for the TMDB v3 REST API, authenticated with a v4 Read Access Token
- Image paths resolved to full image URLs; missing paths omit the field
- Genre ids resolved to genre names, so list results are readable without an extra call
- Detail tools return credits, videos, recommendations, keywords, and external ids in one request
- Region-aware streaming availability backed by JustWatch; region is always an explicit input
Agent-friendly output:
- TMDB attribution on every response in
enrichment.attribution - List responses carry total counts, page/total-pages, and a notice of the filters actually applied
- Empty results return normally with recovery guidance, not as errors
- Watch-provider results always state the region; capped filmographies disclose their full totals
Getting started
A 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 — this server authenticates v3 endpoints with Authorization: Bearer <token>, not the legacy ?api_key= query parameter.
Add it to Claude Code:
claude mcp add tmdb-mcp-server -e TMDB_API_KEY=your-tmdb-read-access-token -- npx -y @cyanheads/tmdb-mcp-server
For other clients, add this to the MCP configuration file:
{
"mcpServers": {
"tmdb-mcp-server": {
"command": "npx",
"args": ["-y", "@cyanheads/tmdb-mcp-server"],
"env": {
"TMDB_API_KEY": "your-tmdb-read-access-token"
}
}
}
}
For Docker or a source build, see Running the server.
Configuration
All configuration is validated at startup via Zod schemas. Key environment variables:
| Variable | Description | Default |
|:---|:---|:---|
| TMDB_API_KEY | Required. TMDB v4 API Read Access Token (JWT). | — |
| TMDB_LANGUAGE | Default response language (e.g. en-US); a per-call language overrides it. | en-US |
| TMDB_DEFAULT_REGION | Region shown in the missing-watch_region hint; never applied to queries. | US |
| MCP_TRANSPORT_TYPE | Transport: stdio or http. | stdio |
| MCP_HTTP_PORT | Port for the HTTP server. | 3010 |
| MCP_AUTH_MODE | Auth mode: none, jwt, or oauth. | none |
| MCP_LOG_LEVEL | Log level (RFC 5424). | info |
| 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 |
| STORAGE_PROVIDER_TYPE | Storage backend. | in-memory |
| OTEL_ENABLED | Enable OpenTelemetry instrumentation (spans, metrics, completion logs). | false |
| OTEL_EXPORTER_OTLP_LOGS_ENDPOINT | OTLP log endpoint. | — |
See .env.example for the full list of optional overrides.
Running the server
L
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
